本章节所说的「令牌」即调用大模型接口(/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/searchQuery 参数(至少填一个搜索条件):
| 参数 | 类型 | 说明 |
|---|---|---|
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/jsonBody 字段:
| 字段 | 类型 | 是否必填 | 默认 | 说明 |
|---|---|---|---|---|
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/ 找到新创建的 id2
调用 8. 获取单个令牌(明文) 拿明文
示例
| 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/jsonQuery 参数:
| 参数 | 类型 | 说明 |
|---|---|---|
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/jsonBody:
| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
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}/keyPath 参数:
| 参数 | 类型 | 说明 |
|---|---|---|
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/jsonBody 字段:
| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
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 <你的系统访问令牌>"