API Key 管理
本页接口使用个人令牌鉴权,不使用被管理的 API Key。个人令牌的获取方式见个人令牌。
Key 管理
获取可用分组
curl "https://api.example.com/api/user/self/groups" \
-H "Authorization: Bearer <PERSONAL_ACCESS_TOKEN>"响应中的对象键为分组名称:
{
"success": true,
"message": "",
"data": {
"default": {
"desc": "默认分组",
"ratio": 1
},
"vip": {
"desc": "优先分组",
"ratio": 0.8
}
}
}| 字段 | 含义 |
|---|---|
data.<group>.desc | 分组说明。 |
data.<group>.ratio | 分组倍率,可能为数字或文本。 |
创建 API Key
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string | 否 | API Key 名称,最多 50 个字符。 |
remain_quota | integer | 否 | 初始剩余额度。unlimited_quota 为 false 时必须大于等于 0,最大值为 500000000000000。 |
unlimited_quota | boolean | 否 | 是否不限制额度。为 true 时忽略 remain_quota。 |
expired_time | integer | 否 | 过期时间,Unix 秒级时间戳;-1 表示永不过期。 |
model_limits_enabled | boolean | 否 | 是否启用模型限制。 |
model_limits | string | 否 | 允许使用的模型名,多个模型以英文逗号分隔。 |
allow_ips | string | 否 | IP 白名单,多个 IP 或 CIDR 每行一个;空字符串表示不限制。 |
group | string | 否 | API Key 使用的分组名称,取自可用分组返回的对象键。 |
auto_groups | array[string] | 条件必填 | group 为 auto 且指定自定义自动分组时传入。 |
cross_group_retry | boolean | 否 | group 为 auto 时是否允许跨分组重试;其他分组不生效。 |
curl "https://api.example.com/api/token/" \
-H "Authorization: Bearer <PERSONAL_ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"name": "production",
"remain_quota": 5000000,
"unlimited_quota": false,
"expired_time": -1,
"model_limits_enabled": false,
"model_limits": "",
"allow_ips": "",
"group": "default",
"cross_group_retry": false
}'响应只返回新 API Key 的 ID。请保存该 ID,后续查询额度、用量或获取完整 Key 时使用。
{
"success": true,
"message": "",
"data": {
"token_id": 12
}
}配置 API Key
该接口只更新请求中显式传入的配置字段。
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string | 否 | API Key 名称,最多 50 个字符。 |
status | integer | 否 | 1 启用,2 禁用。 |
expired_time | integer | 否 | 过期时间,Unix 秒级时间戳;-1 表示永不过期。 |
unlimited_quota | boolean | 否 | 是否不限制额度。 |
model_limits_enabled | boolean | 否 | 是否启用模型限制。 |
model_limits | string | 否 | 允许使用的模型名,多个模型以英文逗号分隔。 |
allow_ips | string | 否 | IP 白名单,多个 IP 或 CIDR 每行一个;空字符串表示不限制。 |
group | string | 否 | API Key 使用的分组名称。 |
auto_groups | array[string] | 条件必填 | group 为 auto 且指定自定义自动分组时传入。 |
cross_group_retry | boolean | 否 | group 为 auto 时是否允许跨分组重试。 |
curl -X POST "https://api.example.com/api/token/12/config" \
-H "Authorization: Bearer <PERSONAL_ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"name": "production-eu",
"status": 1,
"expired_time": -1,
"model_limits_enabled": true,
"model_limits": "gpt-5.6-sol,deepseek-v4-pro",
"allow_ips": "203.0.113.10/32",
"group": "default"
}'响应返回更新后的 API Key 配置对象,key 仍为脱敏值,字段与API Key 列表中的 data.items[] 一致。
查询 API Key 列表
curl "https://api.example.com/api/token/?p=1&page_size=100" \
-H "Authorization: Bearer <PERSONAL_ACCESS_TOKEN>"请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
p | integer | 否 | 页码,从 1 开始,默认 1。 |
page_size | integer | 否 | 每页条数,默认 10,最大 100。 |
响应中的 key 始终为脱敏值,不会返回完整 API Key:
{
"success": true,
"message": "",
"data": {
"page": 1,
"page_size": 100,
"total": 1,
"items": [
{
"id": 12,
"name": "production",
"key": "abcd**********5678",
"status": 1,
"remain_quota": 5000000,
"used_quota": 200000,
"unlimited_quota": false,
"expired_time": -1,
"created_time": 1784505600,
"accessed_time": 1786456736,
"group": "default",
"auto_groups": null,
"cross_group_retry": false,
"model_limits_enabled": false,
"model_limits": "",
"allow_ips": ""
}
]
}
}响应字段
| 字段 | 含义 |
|---|---|
data.page | 当前页码 |
data.page_size | 当前每页条数 |
data.total | API Key 总数 |
data.items[].id | API Key ID |
data.items[].name | API Key 名称 |
data.items[].key | 脱敏后的 API Key |
data.items[].status | 状态:1 启用、2 禁用、3 已过期、4 额度已用尽 |
data.items[].remain_quota | 当前剩余额度 |
data.items[].used_quota | 累计已用额度 |
data.items[].unlimited_quota | 是否不限制额度 |
data.items[].expired_time | 过期时间,Unix 秒级时间戳;-1 表示永不过期 |
data.items[].created_time | 创建时间,Unix 秒级时间戳 |
data.items[].accessed_time | 最近访问时间,Unix 秒级时间戳 |
data.items[].group | API Key 使用的分组 |
data.items[].auto_groups | 自定义自动分组列表;未设置时为 null |
data.items[].cross_group_retry | 是否允许跨分组重试 |
data.items[].model_limits_enabled | 是否启用模型限制 |
data.items[].model_limits | 以英文逗号分隔的模型名 |
data.items[].allow_ips | IP 白名单 |
查询 API Key 配置
curl "https://api.example.com/api/token/12" \
-H "Authorization: Bearer <PERSONAL_ACCESS_TOKEN>"返回单个 API Key 的配置对象,字段与API Key 列表中的 data.items[] 一致,key 仍为脱敏值。
获取 API Key 完整 Key
curl -X POST "https://api.example.com/api/token/12/key" \
-H "Authorization: Bearer <PERSONAL_ACCESS_TOKEN>"{
"success": true,
"message": "",
"data": {
"key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}完整 Key 仅用于服务端安全配置。不要将其返回给浏览器、写入公开代码、截图或日志;泄露后应立即停用或删除对应 API Key。
删除 API Key
curl -X DELETE "https://api.example.com/api/token/12" \
-H "Authorization: Bearer <PERSONAL_ACCESS_TOKEN>"{
"success": true,
"message": ""
}删除后,该 API Key 不能再用于模型请求,且不能通过列表或详情接口查询。
用量与额度
额度查询和用量明细接口的请求频率限制为 60 QPM。超出限制时返回 HTTP 429,请按照 Retry-After 响应头等待后重试。
额度调整
该接口用于对 API Key 的剩余额度执行原子增加、扣减或设置。每次请求必须携带唯一的 Idempotency-Key;使用相同幂等键和相同参数重试时只会执行一次。
请求头
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
Idempotency-Key | string | 是 | 请求头,1 至 128 个非控制字符;同一个 API Key 下必须唯一。 |
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
action | string | 是 | increase 增加额度、decrease 扣减额度、set 设置额度。 |
amount | integer | 是 | 非负整数,最大值为 500000000000000;increase 和 decrease 不能为 0。 |
无限额度的 API Key 不支持额度操作。扣减额度超过当前剩余额度时返回 409;幂等键复用但参数不一致时返回 409。
curl -X POST "https://api.example.com/api/token/12/quota" \
-H "Authorization: Bearer <PERSONAL_ACCESS_TOKEN>" \
-H "Idempotency-Key: quota-operation-20260907-001" \
-H "Content-Type: application/json" \
-d '{
"action": "increase",
"amount": 5000000
}'{
"success": true,
"message": "",
"data": {
"token_id": 12,
"action": "increase",
"amount": 5000000,
"before_quota": 5000000,
"after_quota": 10000000,
"replayed": false,
"operation_id": 21
}
}| 字段 | 类型 | 说明 |
|---|---|---|
data.token_id | integer | API Key ID |
data.action | string | 实际执行的额度操作 |
data.amount | integer | 本次操作额度 |
data.before_quota | integer | 操作前剩余额度 |
data.after_quota | integer | 操作后剩余额度 |
data.replayed | boolean | 是否为同一幂等键的重放响应 |
data.operation_id | integer | 额度操作记录 ID |
额度查询
curl "https://api.example.com/api/token/12/usage" \
-H "Authorization: Bearer <PERSONAL_ACCESS_TOKEN>"{
"success": true,
"message": "",
"data": {
"object": "token_usage",
"token_id": 12,
"name": "production",
"total_granted": 5200000,
"total_used": 200000,
"total_available": 5000000,
"unlimited_quota": false,
"model_limits": {},
"model_limits_enabled": false,
"expires_at": 0
}
}响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
data.object | string | 固定为 token_usage |
data.token_id | integer | API Key ID |
data.name | string | API Key 名称 |
data.total_granted | integer | 当前已用额度与剩余额度之和 |
data.total_used | integer | API Key 累计已用额度 |
data.total_available | integer | API Key 当前剩余额度 |
data.unlimited_quota | boolean | 是否不限制额度 |
data.model_limits | object | 模型限制映射;键为模型名,值为 true |
data.model_limits_enabled | boolean | 是否启用模型限制 |
data.expires_at | integer | 过期时间,Unix 秒级时间戳;0 表示永不过期 |
用量明细
curl "https://api.example.com/api/token/12/logs?limit=50&start_timestamp=1786377600&end_timestamp=1786463999" \
-H "Authorization: Bearer <PERSONAL_ACCESS_TOKEN>"请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
limit | integer | 否 | 返回条数,默认 50,取值范围 1 至 100。 |
start_timestamp | integer | 否 | 起始时间,Unix 秒级时间戳;必须为正数。 |
end_timestamp | integer | 否 | 结束时间,Unix 秒级时间戳;必须为正数,不能早于 start_timestamp。 |
cursor | string | 否 | 上一批响应中的 next_cursor,首次请求不传;该值为不透明游标,请原样传递。 |
响应按创建时间倒序返回。首次请求不传 cursor;has_more 为 true 时,将 next_cursor 原样作为下一批请求的 cursor:
{
"success": true,
"message": "",
"data": {
"items": [
{
"id": 1,
"created_at": 1786456736,
"type": 2,
"token_id": 12,
"token_name": "production",
"model_name": "deepseek-v4-pro",
"quota": 2500,
"prompt_tokens": 1200,
"completion_tokens": 360,
"use_time": 820,
"is_stream": false,
"request_id": "req_xxxxxxxxxxxxxxxx"
}
],
"limit": 50,
"has_more": true,
"next_cursor": "eyJ2ZXJzaW9uIjoxLCJpZCI6MTIzNDU2fQ",
"token_id": 12,
"start_timestamp": 1786377600,
"end_timestamp": 1786463999
}
}响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
data.items | array | 本次返回的用量明细,按创建时间倒序排列 |
data.items[].id | integer | 当前响应中的展示序号 |
data.items[].created_at | integer | 记录创建时间,Unix 秒级时间戳 |
data.items[].type | integer | 日志类型编码 |
data.items[].token_id | integer | API Key ID |
data.items[].token_name | string | API Key 名称 |
data.items[].model_name | string | 模型名称 |
data.items[].quota | integer | 本条记录对应的额度变化 |
data.items[].prompt_tokens | integer | 输入 Token 数量 |
data.items[].completion_tokens | integer | 输出 Token 数量 |
data.items[].use_time | integer | 请求耗时,单位秒 |
data.items[].is_stream | boolean | 是否使用流式响应 |
data.items[].request_id | string | 请求 ID |
data.limit | integer | 本次请求的条数上限 |
data.has_more | boolean | 是否还有更多记录 |
data.next_cursor | string | 后续查询游标;没有更多记录时为空字符串 |
data.token_id | integer | 查询的 API Key ID |
data.start_timestamp | integer | 实际使用的起始时间;未传时为 0 |
data.end_timestamp | integer | 实际使用的结束时间;未传时为 0 |
查询下一批
curl "https://api.example.com/api/token/12/logs?limit=50&start_timestamp=1786377600&end_timestamp=1786463999&cursor=eyJ2ZXJzaW9uIjoxLCJpZCI6MTIzNDU2fQ" \
-H "Authorization: Bearer <PERSONAL_ACCESS_TOKEN>"未传时间范围时查询该 API Key 的全部可用明细。客户端应同时检查 HTTP 状态码和响应中的 success,并在临时错误时使用退避重试。
额度单位说明
amount、remain_quota、before_quota、after_quota和明细中的quota统一使用quota作为计量单位;美元、人民币或 Token 展示值按站点额度配置换算。- 默认换算比例为
500000 quota = 1 USD,例如5000000 quota = 10 USD。 - 美元展示时:
展示金额 = quota ÷ QuotaPerUnit。 - 人民币展示时:
展示金额 = quota ÷ QuotaPerUnit × USDExchangeRate,其中USDExchangeRate由站点配置,表示1 USD = X CNY。例如汇率为7时,500000 quota = ¥7。 - Token 展示模式下,按原始 quota 数值显示,不进行美元或人民币换算。
- 额度调整接口中的
amount使用quota值,不使用货币金额。按默认比例增加10 USD时,应传5000000。
Last updated on