更新 API Key | ToAPIs Documentation

PATCH

/api/v1/api-keys/{api_key_id}

国内用户请注意: 中国大陆用户请使用 https://api.toapis.cn 作为接口地址 (Base URL). 文档示例中的 https://api.toapis.com 请替换为 https://api.toapis.cn.

使用说明

修改指定 Key 的配置, 用于调整名称, 限额, 状态或到期时间等. 请求体至少要包含一个字段; 支持名称, 模型白名单, 日/月限额, unlimited, 剩余额度, 状态和到期时间, 未传入的字段保持原值.

启用与状态

只修改配置不会自动启用 Key.
同一请求中显式传 status=enabled 时, 会按更新后的到期时间, unlimited 和剩余额度一起校验: 已到期或有限额度已耗尽的 Key 无法启用, 返回 409.
已吊销的 Key 返回 404.
不传 status 时持久化状态不变: disabled/expired/exhausted 不会因其他字段更新而自动恢复; enabled Key 的读取态由额度和到期时间派生, 更新后可能恢复为 enabled.

校验与写入

金额字段校验规则与创建接口相同: 不接受 JSON 数字或无法精确换算的值.
model_limits 传 [] 清除模型限制; 日/月限额传 null 或 "0" 清除限制, 但不会重置已用计数.
设置 remaining_credits 会覆盖数据库中已保存的剩余额度, 之后的扣费与退款以新值为基准继续增减; 已产生但尚未写入数据库的批量扣费, 之后仍会照常应用.
更新不会改变累计用量或账户余额.
任一字段校验失败时整个请求不落库, 不会产生部分更新; 更新在事务中按最终配置整体校验, 只写入明确传入的字段.
缓存失效和在途请求的生效边界与现有行为一致.

鉴权

Authorizationstring请求头必填

系统访问令牌, 格式为 Bearer YOUR_SYSTEM_ACCESS_TOKEN. 不接受模型 Key, 无需 X-User-Id. 共用规则见接入方式.

请求参数

api_key_idstring路径必填

自有普通模型 Key 的十进制 ID 字符串, 不是 sk- 密钥.

非空请求体要求 Content-Type: application/json, 最大 16384 字节. 顶层必须是 JSON 对象, 拒绝未知字段, 重复字段和查询参数. 写请求有 10 秒正文读取期限.

statusstring请求体

仅接受 enabled 或 disabled. expired, exhausted 和 deleted 是只读状态.

expires_atstring | null请求体

未来的 RFC 3339 时间, 小数秒向上取整. null 或创建时省略表示永不过期; 更新时省略保持原值.

namestring请求体

名称, 去首尾空白后非空, 最多 50 UTF-8 字节. 省略保持原值.

model_limitsarray请求体

替换整个模型白名单. [] 清除限制, null 不合法. 单项去空白后非空且不含逗号, 按首次出现去重, 拼接后最多 1024 UTF-8 字节.

daily_limit_creditsstring | null请求体

每日限额, 单位 credits. null 或字符串 "0" 表示不限额.

monthly_limit_creditsstring | null请求体

每月限额, 单位 credits. null 或字符串 "0" 表示不限额.

unlimitedboolean请求体

布尔值, 不接受 null. 切回 false 且省略 remaining_credits 时, 沿用数据库中已保存的额度快照, 该额度可能已耗尽. 不自动启用 Key.

remaining_creditsstring | null请求体

设置剩余额度绝对值, 不是追加额度. 最终 unlimited=false 时仅接受非负十进制金额字符串; true 时仅允许省略或 null. 省略时保持已保存的额度不变; null 不会清除无限 Key 已保存的额度.

allow_ipsarray请求体

仅限制这个模型 API Key 的来源 IP 白名单. 字符串数组, 支持单个 IPv4/IPv6 地址; 去首尾空白, 统一格式并去重. [] 清除限制, null 或非法地址返回 400. 不支持 CIDR, 主机名, 端口或 IPv6 zone. PATCH 省略时保持原值.

请求示例

curl --request PATCH \
  --url 'https://api.toapis.com/api/v1/api-keys/43' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"status": "disabled"}'

import requests

response = requests.patch(
    "https://api.toapis.com/api/v1/api-keys/43",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    json={'status': 'disabled'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.toapis.com/api/v1/api-keys/43", {
  method: "PATCH",
  headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN", "Content-Type": "application/json" },
  body: JSON.stringify({"status": "disabled"}),
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());

响应字段

示例使用虚构数据. Key 元数据字段见获取 API Key 详情, 通用响应和错误处理见接入方式.

响应示例

{
  "code": 0,
  "message": "",
  "data": {
    "id": "43",
    "name": "Example Key",
    "key_hint": "****xyz9",
    "status": "disabled",
    "created_at": "2026-11-01T08:00:00Z",
    "expires_at": "2027-01-01T00:00:00Z",
    "unlimited": false,
    "remaining_credits": "500",
    "daily_limit_credits": null,
    "monthly_limit_credits": null,
    "model_limits": [],
    "allow_ips": []
  }
}