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

# API 密钥

> 创建、列出、更新和吊销通用 API 密钥——即终端用户用来调用补全端点的密钥。

API 密钥用于对 `/v1/chat/completions`、`/v1/images/generations`、`/v1/videos/generations` 和 `/v1/audio/*` 进行身份验证。如果你只想从整体上了解 VibeToken 的密钥，请从 [密钥](/essentials/keys) 开始。

**这些端点的身份验证方式：** JWT（已登录的控制台会话）。

## 密钥格式

```
sk-rb-<public_id:12>-<secret:48>
```

`public_id` 可以安全地记录 / 展示（它是用于限流查询的 URL slug）。密钥的 secret 部分**仅在创建时返回一次**——之后不再显示。

***

## 列出 API 密钥

```
GET https://vibetoken.cn/api/v1/api-keys
```

返回已认证用户的所有 API 密钥，按创建时间从新到旧排列。`key_prefix` 始终是经过掩码处理的展示字符串（`first12…last4`）。`full_key` 仅**对明文持久化功能上线后创建的密钥**携带完整明文——旧密钥会省略该字段，其 secret 部分仍不可获取。

### 示例

```bash theme={null}
curl https://vibetoken.cn/api/v1/api-keys \
  -H "Authorization: Bearer <JWT>"
```

### 响应

```json theme={null}
[
  {
    "id": "3c7b3fd5-2563-4d81-847d-1138ed431654",
    "name": "production",
    "key_prefix": "sk-rb-kN2lOa...WL1x",
    "full_key": "sk-rb-kN2lOa7oIlOw-P938cWHaSZi7Z0shwtFMOl0EY089FGBBN6qPeIWL1xODJBle",
    "ip_whitelist": [],
    "rate_limit_rpm": 60,
    "rate_limit_tph": null,
    "rate_limit_tpd": null,
    "is_provisioning": false,
    "disabled": false,
    "created_by": null,
    "created_at": "2026-04-24T10:00:00Z",
    "credit_limit": null,
    "credit_reset_interval": "none",
    "credit_used": 0.0,
    "credit_period_start": null,
    "expires_at": null
  }
]
```

| 字段                      | 说明                                                    |
| ----------------------- | ----------------------------------------------------- |
| `full_key`              | 完整明文密钥。仅对明文持久化功能上线后创建的密钥存在；旧密钥省略该字段。                  |
| `is_provisioning`       | 管理 API 密钥（`sk-rb-prov-…`）为 `true`，普通 API 密钥为 `false`。 |
| `credit_limit`          | 美元消费上限，`null` 表示无限制。                                  |
| `credit_reset_interval` | `none` \| `daily` \| `weekly` \| `monthly`。           |
| `credit_used`           | 当前周期内已花费的美元金额（用于"已用 / 上限"展示）。                         |
| `credit_period_start`   | 当前消费窗口的起始时间，未设置上限时为 `null`。                           |

***

## 创建 API 密钥

```
POST https://vibetoken.cn/api/v1/api-keys
```

### 请求体

<ParamField body="name" type="string" required>
  密钥的人类可读标签。
</ParamField>

<ParamField body="rate_limit_rpm" type="number">
  每分钟最大请求数。省略则无限制。
</ParamField>

<ParamField body="rate_limit_tph" type="number">
  每小时最大 token 数。省略则无限制。
</ParamField>

<ParamField body="rate_limit_tpd" type="number">
  每天最大 token 数。省略则无限制。
</ParamField>

<ParamField body="ip_whitelist" type="string[]">
  最多 10 个允许的 IP（IPv4 / CIDR）。空数组或省略表示不限制。
</ParamField>

<ParamField body="credit_limit" type="number">
  密钥的美元消费上限。省略或设为 `null` 表示无限制。一旦在当前周期内达到上限，密钥将返回 403，直到周期重置。
</ParamField>

<ParamField body="credit_reset_interval" type="string">
  消费窗口的滚动方式：`none`（默认）、`daily`、`weekly` 或 `monthly`。仅在与 `credit_limit` 搭配时有意义。
</ParamField>

<ParamField body="expires_at" type="string (ISO 8601)">
  可选的自动禁用截止时间。此时刻之后，密钥将返回 401。
</ParamField>

### 示例

```bash theme={null}
curl -X POST https://vibetoken.cn/api/v1/api-keys \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production",
    "rate_limit_rpm": 60,
    "ip_whitelist": ["203.0.113.0/24"]
  }'
```

### 响应

```json theme={null}
{
  "id": "3c7b3fd5-2563-4d81-847d-1138ed431654",
  "name": "production",
  "key": "sk-rb-kN2lOa7oIlOw-P938cWHaSZi7Z0shwtFMOl0EY089FGBBN6qPeIWL1xODJBle",
  "created_at": "2026-04-24T10:00:00Z"
}
```

<Warning>
  完整的密钥值**仅在创建时返回一次**。请在响应离开你的终端之前，将其复制到密钥管理器或环境变量中。
</Warning>

***

## 更新 API 密钥

```
PUT https://vibetoken.cn/api/v1/api-keys/{id}
```

### 请求体

以下任意子集：

<ParamField body="name" type="string" />

<ParamField body="ip_whitelist" type="string[]" />

<ParamField body="rate_limit_rpm" type="number" />

<ParamField body="rate_limit_tph" type="number" />

<ParamField body="rate_limit_tpd" type="number" />

<ParamField body="disabled" type="boolean">
  在不丢失历史记录的情况下暂停密钥。`true` 拒绝身份验证；`false` 重新启用。
</ParamField>

<ParamField body="credit_limit" type="number">
  设置美元消费上限。发送数字以设置，省略则保持不变。
</ParamField>

<ParamField body="credit_reset_interval" type="string">
  `none` | `daily` | `weekly` | `monthly`。省略则保持不变。
</ParamField>

<ParamField body="expires_at" type="string (ISO 8601) | null" />

### 示例

```bash theme={null}
# Pause a key without deleting it
curl -X PUT https://vibetoken.cn/api/v1/api-keys/{id} \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{"disabled": true}'
```

### 响应

完整的掩码密钥记录（与列表项结构相同）。

***

## 删除 API 密钥

```
DELETE https://vibetoken.cn/api/v1/api-keys/{id}
```

立即吊销密钥。任何正在进行中、使用该密钥的请求都会在下一次上游调用之前以 401 失败。Redis 中的限流状态会作为删除操作的一部分被清除。

返回 `204 No Content`。

***

## 错误

| 状态码     | 场景                                                         |
| ------- | ---------------------------------------------------------- |
| **401** | 缺少 `Authorization` 头，或 JWT 无效 / 过期。                        |
| **401** | 令牌是 API 密钥——此处需要 JWT。请在控制台创建密钥。                            |
| **402** | （在 `/v1/*` 调用时）密钥在当前周期内已耗尽其 `credit_limit`。                |
| **403** | 密钥存在但已 `disabled` 或超过 `expires_at`。                        |
| **404** | `{id}` 路径未解析到属于此账户的密钥。                                     |
| **422** | `ip_whitelist` 条目超过 10 个，或 `rate_limit_*` 为负数，或 `name` 为空。 |

对 `/v1/*` 调用的限流强制执行在违规时返回 **429** 并附带 `Retry-After`。参见 [限流](/essentials/rate-limits)。