一个端点，
所有模型。

Provisioning Key

当终端用户在你这里拥有账号和额度时，共用一把 key 并不够，需要的是为每个用户单独 签发、分别限额、随时停用。母钥（provisioning key）即用于该场景。

[!NOTE] 回包将 key 嵌成 {key, data:{…}} 两层：顶层是凭据本身，data 下是它的属性。 已按该形状对接过的客户端，只需修改 base_url 与管理凭据。

获取母钥

在控制台的 API Keys 页自助签发：新建时把类型选成 Provisioning (master key)。明文只在创建时出现一次，之后库中只保留指纹。 也可由平台代为签发。

⚠️ 母钥只能管理 key：不能发模型请求、不能读账、不能改渠道和路由。一把既能开无限额度 子钥、又能花钱的凭据，泄露时没有损失上限。

创建子钥

curl https://tare.jamerly.ai/v1/keys \
  -H "Authorization: Bearer $TARE_PROVISIONING_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "user-8f3a2b91",
    "limit": 12.50,
    "external_id": "usr_8f3a2b91",
    "include_byok_in_limit": false
  }'

返回的 key 是完整凭据，只出现一次；data.hash 是后续定位这把 key 的稳定标识。

响应字段

创建、查询、改额度返回的 data 是同一形状：

列表与翻页

GET /v1/keys?limit=&after=，游标分页，包含已停用的 key（更换管理凭据做全量迁移时 需要遍历全部）。

[!NOTE] 控制台的 API Keys 页也能看这些子钥：选「Child keys」那一档， 支持按名称、用途以及外部编号 external_id 搜索。 用于定位单个终端用户的子钥时，比调用列表接口遍历更直接。

{"data": [ /* 与上文相同的结构 */ ], "next_cursor": 8123}

⚠️ 游标是 id 不是 offset。翻页途中若有新 key 创建，offset 会让某一把被跳过或重复出现。

明文不可用时的返回

超过 5 分钟窗口重复创建时，key 为 null，同层多出两个字段：

{"key": null,
 "key_unavailable_reason": "plaintext_window_expired",
 "key_unavailable_message": "The plaintext is only returned within 5 minutes ...",
 "data": { }}

• key_unavailable_reason 是可编程的枚举值，目前只有 plaintext_window_expired， 新增枚举值前会提前通知。按该字段分支。
• key_unavailable_message 是面向人的提示文案，措辞会变，不要用于程序判断。

到期（expires_at）

创建时可传，之后也可改（PATCH 传 expires_at，显式 null = 取消到期）。

• ⚠️ 到期的 key 调模型返回 401，与被吊销的表现完全一致。区分二者等于向持有无效凭据 的人确认「这把 key 曾经存在」。
• ⚠️ 到期不会把 disabled 置为 true，那个字段只表示「被停用」。判断到期请读 expires_at。

母钥轮换

母钥相互独立，一个账号可同时持有多把并分别停用，因此轮换是零停机的：

1. 平台签发新母钥（明文只出现一次）；
2. 配置切到新母钥，新流量走它；
3. 用 /whoami 或任意一次 GET /v1/keys 确认新母钥可用；
4. 通知平台停用旧母钥。

⚠️ 不要先停旧的再换配置。 母钥是创建子钥的唯一入口，停用期间所有新用户注册都会 失败，且无法补偿。

⚠️ 轮换母钥不影响已签发的子钥，子钥是独立凭据，不随母钥失效。

创建幂等

创建请求超时后无法确定是否已创建：重试会多一把，不重试会少一把。带上 external_id 即可避免——同一编号重复创建返回已存在的那把，HTTP 状态码是 200 而非 201。

[!WARNING] 完整 key 只在创建后 5 分钟内可重新取回。

超出窗口后，重复创建仍返回该 key 的 data，但 key 为 null，并附 key_unavailable_reason。

没有这个限制，持有母钥的人只要枚举 external_id 就能反复取回任意子钥的明文，而子钥 能花钱——「母钥自己花不了钱」就不再是损失上限。若 external_id 就是用户 id，枚举成本 接近于零。

真实的创建重试都在秒级，5 分钟足够宽松。需要重新拿到明文时正确做法是换一把：停用 旧的，用新的 external_id 创建——这会留下审计记录，静默重取不会。

[!WARNING] external_id 的唯一性包含已停用的 key：一个编号永久对应一把 key。解封用户请用 PATCH {"disabled": false}，不要用同一个 external_id 再开一把，否则该用户的 历史用量会断成两段。

按外部编号定位

无需维护 external_id → hash 的映射表，可直接用你的编号操作：

curl https://tare.jamerly.ai/v1/keys/external/usr_8f3a2b91 \
  -H "Authorization: Bearer $TARE_PROVISIONING_KEY"

curl -X PATCH https://tare.jamerly.ai/v1/keys/external/usr_8f3a2b91 \
  -H "Authorization: Bearer $TARE_PROVISIONING_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 3.75}'

语义与按 hash 的接口完全一致。单独用 /external/{id} 而不让 {hash} 兼收两种 标识符：两者都是自由文本，放在同一位置时，编号一旦形似 hash，就会静默操作到另一把 key。

改额度 / 停用

curl -X PATCH https://tare.jamerly.ai/v1/keys/$HASH \
  -H "Authorization: Bearer $TARE_PROVISIONING_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 3.75}'

下一次调用即生效，无缓存延迟。这一条是刻意保证的：在扣减用户积分之后下调 limit 时， 任何分钟级的延迟窗口都意味着超额消费。

停用传 {"disabled": true}，同样即时生效。

额度的语义

limit 是累计消费上限，usage 单调递增，不随任何周期清零。积分同步逻辑可以直接 建在这个语义上：

limit = 已消费 + 用户当前剩余积分对应的金额

三道限制互不重叠：

第三道不与月度预算合并，因为积分不会每月自动恢复。

越权访问

只能操作自己名下的 key。不属于你的 hash 返回 404 而不是 403，403 会顺带确认这个 hash 真实存在。

限流

母钥一档是 1200 次/分钟，与模型流量分开计算：改额度的频率约等于你的计费事件频率， 按模型那一档限流会在第一次放量时 429。

四档阈值、调高流程、并发与超时见限流与配额。