> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ariacompute.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/apikeys — 创建 PIN API 密钥

> 在咏唱引擎 PIN 服务上创建新的 API 密钥。完整明文密钥仅返回一次；请在关闭响应前妥善保存。

为 PIN API 生成一个新的用户作用域 API 密钥。你可以指定一个自定义名称以区分不同密钥。完整密钥值仅在此响应中返回，之后无法再次获取。

## 接口

**POST** `/v1/apikeys`

认证：Bearer API 密钥

## 请求体

<ParamField body="name" default="default" type="string">
  新密钥的便于识别的名称。
</ParamField>

## 响应

<ResponseField name="id" type="string">
  唯一的密钥标识符。
</ResponseField>

<ResponseField name="name" type="string">
  为密钥分配的名称。
</ResponseField>

<ResponseField name="key" type="string">
  完整的明文 API 密钥。立即保存；之后不会再显示。
</ResponseField>

<ResponseField name="created_at" type="string">
  密钥创建的 ISO 8601 时间戳。
</ResponseField>

## 示例

```bash theme={null}
curl -X POST http://localhost:8001/v1/apikeys \
  -H "Authorization: Bearer $ARIA_PIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"ci-deploy"}'
```

```json theme={null}
{
  "id": "key_9xYz2AbC3dE4",
  "name": "ci-deploy",
  "key": "ak_live_51HbN9xL5wR8fGqJ3...",
  "created_at": "2025-02-08T11:45:00Z"
}
```

使用创建 API 密钥接口为编程访问生成新的 API 密钥。提供一个名称用于识别该密钥。完整密钥值仅返回一次，之后无法再次获取。

## 接口

```http theme={null}
POST /v1/apikeys
```

## 认证

需要有效的 `Authorization: Bearer <jwt-or-api-key>` 头。

## 请求体

<ParamField body="name" type="string" required>
  新 API 密钥的便于识别的名称。
</ParamField>

## 响应

<ResponseField name="id" type="string">
  所创建 API 密钥的唯一标识符。
</ResponseField>

<ResponseField name="name" type="string">
  请求中提供的名称。
</ResponseField>

<ResponseField name="key" type="string">
  完整 API 密钥值。仅显示一次；请妥善保存。
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://ariapin.example.com:8001/v1/apikeys \
    -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
    -H "Content-Type: application/json" \
    -d '{"name":"production"}'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 0,
    "data": {
      "id": "key_xyz",
      "name": "production",
      "key": "pin_live_abc123..."
    },
    "message": ""
  }
  ```
</ResponseExample>