修改 API Key

PATCH /api/open/v1/keys/:id

请求参数

只更新请求体中出现的字段，未出现的字段保持不变。至少需要一个可修改字段：空请求体、null 或 {} 返回 400。

参数	位置	类型	必填	说明
id	path	integer	是	Key ID，正整数
name	body	string	否	名称，去除首尾空白后不能为空，最长 50 个字符（按字符计，不是字节）
status	body	integer	否	1 启用、2 禁用；其他取值返回 400（3 / 4 由系统自动设置）
expired_time	body	integer	否	过期时间，unix 秒；0 / -1 表示永不过期
remain_amount	body	number	否	可用金额，站点币种，两位小数；不能为负数且不能超过上限
unlimited	body	boolean	否	是否无限额度
model_limits_enabled	body	boolean	否	是否启用模型白名单
model_limits	body	string	否	允许的模型，英文逗号分隔
allow_ips	body	string	否	允许的 IP，换行分隔；空字符串表示不限制

status 只接受 1（启用）或 2（禁用）。启用要求本次更新后 Key 可用：未过期（expired_time 为 -1 或在未来）且无限额度或 remain_amount > 0，否则返回 400。可以在同一请求里一起传，如 {"status": 1, "expired_time": 1767225600}。禁用不限制原状态；显式传 status 优先于自动恢复。

请求示例

为额度已耗尽的 Key 补充额度（Key 会自动恢复为启用状态）：

curl -X PATCH https://www.routeapi.ai/api/open/v1/keys/12 \
  -H "Authorization: Bearer $ROUTEAPI_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"remain_amount": 20.00}'

延长有效期限：

curl -X PATCH https://www.routeapi.ai/api/open/v1/keys/12 \
  -H "Authorization: Bearer $ROUTEAPI_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expired_time": 1767225600}'

禁用 Key（在重新启用前，用它发起的请求都会被拒绝）：

curl -X PATCH https://www.routeapi.ai/api/open/v1/keys/12 \
  -H "Authorization: Bearer $ROUTEAPI_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": 2}'

重新启用，并在同一请求里延长有效期，确保启用后可用：

curl -X PATCH https://www.routeapi.ai/api/open/v1/keys/12 \
  -H "Authorization: Bearer $ROUTEAPI_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": 1, "expired_time": 1767225600}'

响应示例

返回更新后的 Key 对象，key 为脱敏值：

{
  "success": true,
  "message": "",
  "data": {
    "id": 12,
    "name": "bot",
    "key": "sk-abcd**********wxyz",
    "status": 1,
    "created_time": 1729000000,
    "accessed_time": 1729000000,
    "expired_time": -1,
    "remain_amount": 20.00,
    "unlimited": false,
    "used_amount": 10.00,
    "model_limits_enabled": false,
    "model_limits": "",
    "allow_ips": ""
  }
}

字段说明见 Key 对象。

错误

HTTP	code	场景
400	invalid_request	id 不是正整数，或请求体不是合法 JSON
400	invalid_request	请求体为空、null 或没有任何可修改字段
400	invalid_request	status 不是 1 或 2（3 / 4 由系统自动设置）
400	invalid_request	Key 仍处于过期或耗尽状态时传 status: 1；需延长 expired_time、补足 remain_amount 或改为无限额度（可在同一请求里一起传）
400	invalid_request	名称超过 50 个字符，或 remain_amount 为负数、超过上限
400	invalid_request	expired_time 不是未来时间（且不是 0 / -1），或超出 9999-12-31
400	invalid_request	对无限额度 Key 单独传 remain_amount，或把无限额度 Key 改为有限额度时未传 remain_amount
404	not_found	Key 不存在或不属于你

其他通用错误码见 开放平台 API 错误。

说明

• 单独传 remain_amount：对有限额度 Key 直接生效；对无限额度 Key 返回 400，需要同时传 "unlimited": false。
• "unlimited": false 且未传 remain_amount：对无限额度的 Key 返回 400（避免余额被清零）；本来就是有限额度的 Key 保持原余额不变。
• 过期（3）或耗尽（4）的 Key，在本次更新后若变为可用（延长 expired_time、补足 remain_amount、改为无限额度），会自动恢复为启用（1）。自动恢复只在本次请求没有传 status 时生效。
• 2 是你手动禁用的状态，不会自动恢复，需要传 status: 1 重新启用。Key 不在 1 状态时，用它调用模型接口会被拒绝。
• 先完成全部校验再一次性写入：任一字段校验失败都返回 400，且不会修改任何字段。
• 通过开放平台 API 修改 Key 会记录审计日志。