Skip to Content
用户与 API KeyAPI Key 管理

API Key 管理

本页接口使用个人令牌鉴权,不使用被管理的 API Key。个人令牌的获取方式见个人令牌。

Key 管理

获取可用分组

接口GET /api/user/self/groups
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

接口POST /api/token/

请求参数

参数类型必填说明
namestring否API Key 名称,最多 50 个字符。
remain_quotainteger否初始剩余额度。unlimited_quota 为 false 时必须大于等于 0,最大值为 500000000000000。
unlimited_quotaboolean否是否不限制额度。为 true 时忽略 remain_quota。
expired_timeinteger否过期时间,Unix 秒级时间戳;-1 表示永不过期。
model_limits_enabledboolean否是否启用模型限制。
model_limitsstring否允许使用的模型名,多个模型以英文逗号分隔。
allow_ipsstring否IP 白名单,多个 IP 或 CIDR 每行一个;空字符串表示不限制。
groupstring否API Key 使用的分组名称,取自可用分组返回的对象键。
auto_groupsarray[string]条件必填group 为 auto 且指定自定义自动分组时传入。
cross_group_retryboolean否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

该接口只更新请求中显式传入的配置字段。

接口POST /api/token/{id}/config

请求参数

参数类型必填说明
namestring否API Key 名称,最多 50 个字符。
statusinteger否1 启用,2 禁用。
expired_timeinteger否过期时间,Unix 秒级时间戳;-1 表示永不过期。
unlimited_quotaboolean否是否不限制额度。
model_limits_enabledboolean否是否启用模型限制。
model_limitsstring否允许使用的模型名,多个模型以英文逗号分隔。
allow_ipsstring否IP 白名单,多个 IP 或 CIDR 每行一个;空字符串表示不限制。
groupstring否API Key 使用的分组名称。
auto_groupsarray[string]条件必填group 为 auto 且指定自定义自动分组时传入。
cross_group_retryboolean否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 列表

接口GET /api/token/
curl "https://api.example.com/api/token/?p=1&page_size=100" \ -H "Authorization: Bearer <PERSONAL_ACCESS_TOKEN>"

请求参数

参数类型必填说明
pinteger否页码,从 1 开始,默认 1。
page_sizeinteger否每页条数,默认 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.totalAPI Key 总数
data.items[].idAPI Key ID
data.items[].nameAPI 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[].groupAPI Key 使用的分组
data.items[].auto_groups自定义自动分组列表;未设置时为 null
data.items[].cross_group_retry是否允许跨分组重试
data.items[].model_limits_enabled是否启用模型限制
data.items[].model_limits以英文逗号分隔的模型名
data.items[].allow_ipsIP 白名单

查询 API Key 配置

接口GET /api/token/{id}
curl "https://api.example.com/api/token/12" \ -H "Authorization: Bearer <PERSONAL_ACCESS_TOKEN>"

返回单个 API Key 的配置对象,字段与API Key 列表中的 data.items[] 一致,key 仍为脱敏值。

获取 API Key 完整 Key

接口POST /api/token/{id}/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

接口DELETE /api/token/{id}
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;使用相同幂等键和相同参数重试时只会执行一次。

接口POST /api/token/{id}/quota

请求头

参数类型必填说明
Idempotency-Keystring是请求头,1 至 128 个非控制字符;同一个 API Key 下必须唯一。

请求参数

参数类型必填说明
actionstring是increase 增加额度、decrease 扣减额度、set 设置额度。
amountinteger是非负整数,最大值为 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_idintegerAPI Key ID
data.actionstring实际执行的额度操作
data.amountinteger本次操作额度
data.before_quotainteger操作前剩余额度
data.after_quotainteger操作后剩余额度
data.replayedboolean是否为同一幂等键的重放响应
data.operation_idinteger额度操作记录 ID

额度查询

接口GET /api/token/{id}/usage
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.objectstring固定为 token_usage
data.token_idintegerAPI Key ID
data.namestringAPI Key 名称
data.total_grantedinteger当前已用额度与剩余额度之和
data.total_usedintegerAPI Key 累计已用额度
data.total_availableintegerAPI Key 当前剩余额度
data.unlimited_quotaboolean是否不限制额度
data.model_limitsobject模型限制映射;键为模型名,值为 true
data.model_limits_enabledboolean是否启用模型限制
data.expires_atinteger过期时间,Unix 秒级时间戳;0 表示永不过期

用量明细

接口GET /api/token/{id}/logs
curl "https://api.example.com/api/token/12/logs?limit=50&start_timestamp=1786377600&end_timestamp=1786463999" \ -H "Authorization: Bearer <PERSONAL_ACCESS_TOKEN>"

请求参数

参数类型必填说明
limitinteger否返回条数,默认 50,取值范围 1 至 100。
start_timestampinteger否起始时间,Unix 秒级时间戳;必须为正数。
end_timestampinteger否结束时间,Unix 秒级时间戳;必须为正数,不能早于 start_timestamp。
cursorstring否上一批响应中的 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.itemsarray本次返回的用量明细,按创建时间倒序排列
data.items[].idinteger当前响应中的展示序号
data.items[].created_atinteger记录创建时间,Unix 秒级时间戳
data.items[].typeinteger日志类型编码
data.items[].token_idintegerAPI Key ID
data.items[].token_namestringAPI Key 名称
data.items[].model_namestring模型名称
data.items[].quotainteger本条记录对应的额度变化
data.items[].prompt_tokensinteger输入 Token 数量
data.items[].completion_tokensinteger输出 Token 数量
data.items[].use_timeinteger请求耗时,单位秒
data.items[].is_streamboolean是否使用流式响应
data.items[].request_idstring请求 ID
data.limitinteger本次请求的条数上限
data.has_moreboolean是否还有更多记录
data.next_cursorstring后续查询游标;没有更多记录时为空字符串
data.token_idinteger查询的 API Key ID
data.start_timestampinteger实际使用的起始时间;未传时为 0
data.end_timestampinteger实际使用的结束时间;未传时为 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