请输入
菜单

令牌管理(API Key)

本章节所说的「令牌」即调用大模型接口(/v1/chat/completions 等)时使用的 API Key,形如 sk-xxxx,与 系统访问令牌不同。

通用规范:

•令牌状态码:1=启用、2=已停用、3=已过期、4=已耗尽。

1. 获取令牌列表

分页查询你名下的所有令牌。

请求

•方法:GET
•路径:/api/token/

Query 参数(分页可选):

参数 类型 默认 说明
p int 1 页码(从 1 开始)
page_size int 10 每页条数,上限 100

响应

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 3,
    "items": [
      {
        "id": 1001,
        "user_id": 12345,
        "key": "Xyz8**********DefG",
        "status": 1,
        "name": "my-key",
        "created_time": 1785225000,
        "accessed_time": 1785225000,
        "expired_time": -1,
        "remain_quota": 500000,
        "unlimited_quota": false,
        "model_limits_enabled": false,
        "model_limits": "",
        "allow_ips": "",
        "used_quota": 0,
        "group": "",
        "cross_group_retry": false,
        "DeletedAt": null,
        "auto_groups": null
      }
    ]
  }
}

令牌对象字段:

字段 类型 说明
id int 令牌 ID
user_id int 所属用户 ID
key string 令牌明文经过脱敏(前 4 位 + 星号 + 末 4 位)。查看明文见 8. 获取单个令牌(明文)
status int 令牌状态
name string 令牌名称
created_time int 创建时间(秒级 Unix 时间戳)
accessed_time int 最近一次使用时间
expired_time int 过期时间;-1 表示永不过期
remain_quota int 剩余额度(quota 单位)
unlimited_quota boolean 是否无限额度;为 true 时 remain_quota 无效
used_quota int 累计已用额度
model_limits_enabled boolean 是否启用「仅可用指定模型」限制
model_limits string 可用模型名,逗号分隔
allow_ips string IP 白名单,换行分隔;空表示不限
group string 分组;空表示继承账号默认分组
cross_group_retry boolean 跨分组重试(仅 auto 分组生效)
auto_groups string[] / null 自动分组列表;未设置时为 null
DeletedAt null 当前接口实际返回的软删除时间字段;正常返回令牌时为 null,客户端不应依赖该字段

示例

curl -sS "https://ailink.nativex.com/api/token/?p=1&page_size=20" \
  -H "Authorization: Bearer <你的系统访问令牌>"

2. 搜索令牌

按名称或按 API Key 明文搜索你名下的令牌。

请求

•方法:GET
•路径:/api/token/search

Query 参数(至少填一个搜索条件):

参数 类型 说明
keyword string 按令牌名称模糊搜索
token string 按 API Key 明文精确匹配(自动去除 sk- 前缀)
p int 页码
page_size int 每页条数

响应

与「获取令牌列表」结构一致。

示例

•搜索接口有独立限流,短时间内频繁调用会返回 429。
# 按名称搜
curl -sS "https://ailink.nativex.com/api/token/search?keyword=生产" \
  -H "Authorization: Bearer <你的系统访问令牌>"

# 按明文 key 搜
curl -sS "https://ailink.nativex.com/api/token/search?token=Xyz8AbcDefGhiJklMnoPqrStuVwxYz0123456789AbcDefG" \
  -H "Authorization: Bearer <你的系统访问令牌>"

说明


3. 获取单个令牌

按 ID 查询令牌详情(明文密钥仍脱敏,取明文见 8)。

请求

•方法:GET
•路径:/api/token/{id}

Path 参数:

参数 类型 说明
id int 令牌 ID

响应

{
  "success": true,
  "message": "",
  "data": {
    "id": 1001,
    "user_id": 12345,
    "key": "Xyz8**********DefG",
    "status": 1,
    "name": "my-key",
    "created_time": 1785225000,
    "accessed_time": 1785225000,
    "expired_time": -1,
    "remain_quota": 500000,
    "unlimited_quota": false,
    "model_limits_enabled": false,
    "model_limits": "",
    "allow_ips": "",
    "used_quota": 0,
    "group": "",
    "cross_group_retry": false,
    "DeletedAt": null,
    "auto_groups": null
  }
}

字段含义与「获取令牌列表」中每一项相同。

常见错误

message 处理
令牌不存在 id 无效或不属于当前账户

4. 创建令牌

创建一个新的 API Key。

请求

•方法:POST
•路径:/api/token/
•Content-Type:application/json

Body 字段:

字段 类型 是否必填 默认 说明
name string 是 — 令牌名称,≤ 50 字符
expired_time int 否 -1 过期时间戳(秒);-1 表示永不过期
remain_quota int 条件 0 额度(quota 单位)。unlimited_quota=false 时必填且 ≥ 0
unlimited_quota boolean 否 false 是否无限额度
model_limits_enabled boolean 否 false 是否启用模型限制
model_limits string 否 "" 允许调用的模型,逗号分隔(model_limits_enabled=true 时生效)
allow_ips string 否 "" IP 白名单,换行分隔;空表示不限
group string 否 "" 分组;空表示继承账号默认分组
cross_group_retry boolean 否 false 跨分组重试(仅 auto 分组生效)
auto_groups string[] 否 — 自动分组列表;不传该字段表示不设置,传空数组会清空已设置的自动分组

响应

{
  "success": true,
  "message": ""
}

响应不返回明文 API Key。如需拿明文:

1
调用「获取令牌列表」GET /api/token/ 找到新创建的 id

示例

message 处理
令牌名称过长 名称截断至 50 字符以内
已达到最大令牌数量限制 (N) 删除不用的令牌,或联系支持提升上限
令牌额度不能为负 remain_quota 传入负值
令牌额度超过最大值 单个令牌额度过大
•创建操作有独立限流。
•unlimited_quota=true 时,令牌本身不限额度,但仍受账户总余额约束——余额耗尽后所有令牌都会调用失败。
curl -sS -X POST "https://ailink.nativex.com/api/token/" \
  -H "Authorization: Bearer <你的系统访问令牌>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "生产环境-主 Key",
    "remain_quota": 500000,
    "unlimited_quota": false,
    "expired_time": -1,
    "model_limits_enabled": false,
    "model_limits": "",
    "allow_ips": "",
    "group": "",
    "cross_group_retry": false
  }'

常见错误

说明


5. 更新令牌

更新令牌属性;也可只更新状态。

请求

•方法:PUT
•路径:/api/token/
•Content-Type:application/json

Query 参数:

参数 类型 说明
status_only string 非空时只更新 status 字段,其他字段忽略。用于快速启用/停用令牌

Body 字段:

字段 类型 是否必填 说明
id int 是 目标令牌 ID
status int 条件 令牌状态:1=启用、2=已停用、3=已过期、4=已耗尽(status_only 模式下必填)
name string 否 名称(≤ 50 字符)
expired_time int 否 过期时间戳
remain_quota int 否 剩余额度
unlimited_quota boolean 否 是否无限额度
model_limits_enabled boolean 否 是否启用模型限制
model_limits string 否 允许调用的模型(逗号分隔)
allow_ips string 否 IP 白名单
group string 否 分组
cross_group_retry boolean 否 跨分组重试
auto_groups string[] 否 自动分组列表;不传该字段表示不修改,传空数组会清空已设置的自动分组

响应

{
  "success": true,
  "message": "",
  "data": {
    "id": 1001,
    "status": 1,
    "name": "my-key",
    "...": "..."
  }
}

data 结构同「获取单个令牌」。

示例

只启用 / 停用令牌:

# 启用
curl -sS -X PUT "https://ailink.nativex.com/api/token/?status_only=1" \
  -H "Authorization: Bearer <你的系统访问令牌>" \
  -H "Content-Type: application/json" \
  -d '{"id": 1001, "status": 1}'

# 停用
curl -sS -X PUT "https://ailink.nativex.com/api/token/?status_only=1" \
  -H "Authorization: Bearer <你的系统访问令牌>" \
  -H "Content-Type: application/json" \
  -d '{"id": 1001, "status": 2}'

全量更新(改名字 + 改额度 + 改分组):

message 处理
令牌不存在 id 无效或不属于当前账户
已过期的令牌无法启用 需要先修改 expired_time
已耗尽的令牌无法启用 需要先调整 remain_quota 或设为无限额度
curl -sS -X PUT "https://ailink.nativex.com/api/token/" \
  -H "Authorization: Bearer <你的系统访问令牌>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 1001,
    "status": 1,
    "name": "生产-主Key",
    "remain_quota": 1000000,
    "unlimited_quota": false,
    "expired_time": -1,
    "group": ""
  }'

常见错误


6. 删除令牌

按 ID 永久删除令牌。删除后,该令牌调用大模型接口将立即失败。

请求

•方法:DELETE
•路径:/api/token/{id}

Path 参数:

参数 类型 说明
id int 令牌 ID

响应

curl -sS -X DELETE "https://ailink.nativex.com/api/token/1001" \
  -H "Authorization: Bearer <你的系统访问令牌>"
•已用额度(used_quota)不会因删除而返还。
•已产生的调用日志仍会保留在历史记录中。
{
  "success": true,
  "message": ""
}

示例

说明


7. 批量删除令牌

一次删除多个令牌。

请求

•方法:POST
•路径:/api/token/batch
•Content-Type:application/json

Body:

字段 类型 是否必填 说明
ids int[] 是 要删除的令牌 ID 数组,非空

响应

字段 说明
data 实际删除的令牌数量(不属于当前账户或已删除的 ID 会被跳过)
curl -sS -X POST "https://ailink.nativex.com/api/token/batch" \
  -H "Authorization: Bearer <你的系统访问令牌>" \
  -H "Content-Type: application/json" \
  -d '{"ids": [1001, 1002, 1003]}'
message 处理
无效的参数 ids 为空或格式错误
{
  "success": true,
  "message": "",
  "data": 3
}

示例

常见错误


8. 获取单个令牌(明文)

获取指定令牌的明文 API Key,用于配置到你的应用中。此接口有严格限流。

请求

•方法:POST
•路径:/api/token/{id}/key

Path 参数:

参数 类型 说明
id int 令牌 ID

无请求体。

响应

字段 说明
data.key 令牌明文,用于以 Authorization: Bearer <key> 调用大模型接口
curl -sS -X POST "https://ailink.nativex.com/api/token/1001/key" \
  -H "Authorization: Bearer <你的系统访问令牌>"
{
  "success": true,
  "message": "",
  "data": {
    "key": "Xyz8AbcDefGhiJklMnoPqrStuVwxYz0123456789AbcDefG"
  }
}

示例

拿到明文后调用大模型:

•请只在必要时调用。理想使用方式:创建令牌后取一次明文,妥善保存在你的密钥管理系统中,之后由你的应用直接读取。
•本接口不允许缓存(服务端会强制设置 no-cache 头)。
•触发限流会返回 429,此时需要间隔一段时间再重试。
HTTP message 处理
200 令牌不存在 id 无效或不属于当前账户
429 — 短时间内查询过于频繁,稍等再试
curl -sS -X POST "https://ailink.nativex.com/v1/chat/completions" \
  -H "Authorization: Bearer Xyz8AbcDefGhiJklMnoPqrStuVwxYz0123456789AbcDefG" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role":"user","content":"ping"}]
  }'

说明

常见错误


9. 批量获取令牌明文

一次获取多个令牌的明文 API Key。同样有严格限流,用途和限制与「获取单个令牌(明文)」一致。

请求

•方法:POST
•路径:/api/token/batch/keys
•Content-Type:application/json

Body 字段:

字段 类型 是否必填 说明
ids int[] 是 要查询的令牌 ID 数组,非空,单次最多 100 个

响应

字段 说明
data.keys 以令牌 ID(字符串形式)为 key、明文 API Key 为 value 的映射;不属于当前账户的 ID 会被静默跳过,不会出现在返回结果中
curl -sS -X POST "https://ailink.nativex.com/api/token/batch/keys" \
  -H "Authorization: Bearer <你的系统访问令牌>" \
  -H "Content-Type: application/json" \
  -d '{"ids": [1001, 1002]}'
message 处理
无效的参数 ids 为空或未提供
批量操作数量不能超过 100 单次 ids 数组超过 100 个,需要分批查询
•本接口不允许缓存(服务端会强制设置 no-cache 头)。
•触发限流会返回 429,此时需要间隔一段时间再重试。
{
  "success": true,
  "message": "",
  "data": {
    "keys": {
      "1001": "Xyz8AbcDefGhiJklMnoPqrStuVwxYz0123456789AbcDefG",
      "1002": "Abc1DefGhiJklMnoPqrStuVwxYz0123456789AbcDefGhij"
    }
  }
}

示例

常见错误

说明


10. 获取可用自动分组

获取当前账号可选择的自动分组列表及最多可配置的分组数量。

请求

•方法:GET
•路径:/api/token/auto-groups

响应

{
  "success": true,
  "message": "",
  "data": {
    "groups": [
      "default",
      "vip"
    ],
    "max_count": 5
  }
}
字段 类型 说明
data.groups string[] 当前账号可选择的自动分组名称
data.max_count int 单个令牌最多可配置的自动分组数量

示例

curl -sS "https://ailink.nativex.com/api/token/auto-groups" \
  -H "Authorization: Bearer <你的系统访问令牌>"
最近修改: 2026-10-29