API 密钥

API 密钥用于对 /v1/chat/completions、/v1/images/generations、/v1/videos/generations 和 /v1/audio/* 进行身份验证。如果你只想从整体上了解 VibeToken 的密钥，请从密钥开始。 这些端点的身份验证方式： 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 部分仍不可获取。

示例

curl https://vibetoken.cn/api/v1/api-keys \
  -H "Authorization: Bearer <JWT>"

响应

[
  {
    "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

请求体

string

必填

密钥的人类可读标签。

number

每分钟最大请求数。省略则无限制。

number

每小时最大 token 数。省略则无限制。

number

每天最大 token 数。省略则无限制。

string[]

最多 10 个允许的 IP（IPv4 / CIDR）。空数组或省略表示不限制。

number

密钥的美元消费上限。省略或设为 null 表示无限制。一旦在当前周期内达到上限，密钥将返回 403，直到周期重置。

string

消费窗口的滚动方式：none（默认）、daily、weekly 或 monthly。仅在与 credit_limit 搭配时有意义。

string (ISO 8601)

可选的自动禁用截止时间。此时刻之后，密钥将返回 401。

示例

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"]
  }'

响应

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

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

更新 API 密钥

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

请求体

以下任意子集：

string

string[]

number

boolean

在不丢失历史记录的情况下暂停密钥。true 拒绝身份验证；false 重新启用。

number

设置美元消费上限。发送数字以设置，省略则保持不变。

string

none | daily | weekly | monthly。省略则保持不变。

string (ISO 8601) | 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。参见限流。

快速开始

API 参考

密钥格式

列出 API 密钥

示例

响应

创建 API 密钥

请求体

示例

响应

更新 API 密钥

请求体

示例

响应

删除 API 密钥

错误

​密钥格式

​列出 API 密钥

​示例

​响应

​创建 API 密钥

​请求体

​示例

​响应

​更新 API 密钥

​请求体

​示例

​响应

​删除 API 密钥

​错误

密钥格式

列出 API 密钥

示例

响应

创建 API 密钥

请求体

示例

响应

更新 API 密钥

请求体

示例

响应

删除 API 密钥

错误