管理 API Key 与查询用量

凭据与权限

本页请求使用管理 Token，不能用模型 API Key 代替。请管理员按操作授予所需 scope；读、写和用量汇总权限相互独立，写权限不隐含读权限。

API Key 管理使用绑定目标团队的管理 Token。api_keys:write 还允许读取完整密钥和移除预算限制，只交给可信后端。组织 Token 不能管理 Key。将 YOUR_MANAGEMENT_TOKEN 替换为具有当前操作权限的完整管理 Token。

取得团队编号和 API Key ID

本页金额统一使用与控制台一致的 Credits（ℂ），以精确十进制字符串返回，最多六位小数。成功响应通过 X-CRR-Credit-Unit: credits 标明金额单位；汇总响应的 schema_version 为 2。

1. 在管理控制台打开目标团队，点击团队名称下方的编号，复制纯编号，例如 T-TU214G。替换请求路径中的 TEAM_CODE。这是团队编号，不是组织编号，也不是团队 UUID。
2. 打开该团队的 API Key 页签，找到目标 API Key，选择 更多 → 复制 API Key ID。用该 UUID 替换请求中的 API_KEY_ID。该按钮只复制已有资源 ID，不读取密钥明文；复制 API Key 是另一项敏感操作。

本页请求使用生产管理服务 https://creative-reasoning.com。服务端也可以用具有 api_keys:read 的管理 Token 列出 API Key：

curl \
  -H "Authorization: Bearer YOUR_MANAGEMENT_TOKEN" \
  "https://creative-reasoning.com/api/v1/management/teams/TEAM_CODE/api-keys"

HTTP 200 返回数组。选择目标项的 id 作为 API_KEY_ID，用 label 和 key_prefix 辅助辨认；不要拿前缀代替 ID。列表不返回密钥明文，也不需要 api_keys:write。创建响应的 id 是同一个资源 ID，无需创建新 Key 来查询旧 Key。

API Key ID 只是 API Key 的属性，不能调用模型。模型调用使用 API Key 明文；本页管理操作使用请求头中的管理 Token。响应中的 team_id 仍是团队 UUID，不能放回要求 team_code 的路径。

创建服务专用 Key

需要 api_keys:write。

若服务不需要预支，显式发送 overdraft_enabled: false。省略该字段会继承团队和组织的有效预支开关；启用预支而未指定上限时，Key 级上限默认为无限。

curl \
  -X POST \
  -H "Authorization: Bearer YOUR_MANAGEMENT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"label":"batch-worker","overdraft_enabled":false}' \
  "https://creative-reasoning.com/api/v1/management/teams/TEAM_CODE/api-keys"

在 HTTP 201 响应中保存 id 和 key。id 是 API Key ID（UUID），用它替换后续请求中的 API_KEY_ID；它不是凭据，不能调用模型。key 是 API Key 明文，存入秘密管理系统供服务调用模型。以下管理操作继续使用管理 Token。

设置周期消费预算

在把 Key 交给服务前设置预算。创建 Key 和设置预算是两次独立操作；预算请求失败时，不要启动该 Key 的工作负载。

不改变起算点时，不发送 starts_at。首次设置默认从请求时刻起算，更新时保留原起算点。显式修改该字段会重新选择消费统计范围。

curl \
  -X PUT \
  -H "Authorization: Bearer YOUR_MANAGEMENT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"amount":"1000","window_days":7,"is_enabled":true}' \
  "https://creative-reasoning.com/api/v1/management/teams/TEAM_CODE/api-keys/API_KEY_ID/budgets/windowed"

核对 HTTP 200 响应中的 amount、window_days 和 starts_at。金额输入和输出均使用 Credits（ℂ）；本例设置的预算为 1000 ℂ，周期为固定 7 天。预算 amount 和 Key 的 overdraft_limit 必须是 0.000005 ℂ 的整数倍，最大 49999999999999.999995 ℂ；超出范围或精度要求的输入返回 400，不自动舍入。总额预算改用 budgets/all_time，并省略 window_days。

若要展示已用、剩余和下次重置时间，另外申请独立的 api_keys:read，按下节查询剩余额度与重置时间。写权限不包含读权限。预算配置成功不代表策略已同步到所有模型请求。

查询剩余额度与重置时间

需要 api_keys:read。

curl \
  -H "Authorization: Bearer YOUR_MANAGEMENT_TOKEN" \
  "https://creative-reasoning.com/api/v1/management/teams/TEAM_CODE/api-keys/API_KEY_ID/quota"

从 HTTP 200 响应中读取 available_credits，以及 overdraft.remaining_credits。查看本周期消费和余额时，读取 budgets.windowed.used_credits 和 remaining_credits；查看重置时间时，读取 resets_at。

按以下边界展示查询结果：

• 额度字段的单位是 Credits，不是模型 token 数。余额、预支余量、预算余额不可相加为一个可消费总额，也不能据此判定一定可调用。
• all_time 是自 starts_at 起的总额预算，不自动重置；windowed 是从该时刻起每 N 天重置的周期预算。未配置、停用或未开始时部分字段为 null，不要显示为零。重置不充值，也不清除预支欠款。
• 快照采用最终一致性。保留 observed_at 供展示，允许近期消费稍后出现。不要把查询结果作为同步放行依据。

字段状态、无限预支和空值的完整定义见管理 API。

查询历史 token 用量

查询历史报表需要独立的 usage:aggregate。可由管理员为同一个 Token 明确授予，或签发另一个仅有该 scope 的 Token；api_keys:read 不隐含此权限。

请求中的 start 与 end 使用 RFC3339 时间。下面示例使用 2026-08-31T16:00:00Z 和 2026-09-01T16:00:00Z，表示上海时间 9 月 1 日全天。Z 表示 UTC，也可写显式偏移 +08:00。区间为 [start, end)，结束时刻不计入。

curl --get \
  -H "Authorization: Bearer YOUR_MANAGEMENT_TOKEN" \
  --data-urlencode "api_key_id=API_KEY_ID" \
  --data-urlencode "start=2026-08-31T16:00:00Z" \
  --data-urlencode "end=2026-09-01T16:00:00Z" \
  --data-urlencode "timezone=Asia/Shanghai" \
  "https://creative-reasoning.com/api/v1/management/usage/summary"

timezone 解释裸日期并决定时间分桶，不会重新解释 RFC3339 中的偏移。接口不接受 Unix 秒或毫秒数字。推荐程序始终发送带 Z 或偏移的 RFC3339；若使用 YYYY-MM-DD，end 会包含该日期全天，与精确时间的排他上界不同。

查看该时间段的总消费，读取 totals.credits.after_discount，单位为 Credits。例如 "105.21352" 表示消费 105.21352 ℂ，不是 token 数或人民币金额。分组时顶层 totals 仍覆盖整个过滤窗口，不是当前页之和。

查看 token 用量，读取 totals.tokens.input、totals.tokens.output 中各维度的整数字符串。不要把可能重叠的 token 维度相加。这些数值来自已完成文本账单，不代表完整模型用量；预算采用消费记账时间，与历史请求区间不一定一致。

仅查 embedding 时增加 --data-urlencode "request_type=embedding"。embedding 的已落定账单计入该 token 视图；缺失的计费维度不代表真实消耗为零。

若需要核对一次调用，保存模型响应中的 x-cr-usage-id，使用具有 usage:read 的 Token 调用单条查账接口。

服务下线后撤销 Key

先停止工作负载，再撤销 Key。撤销不取消已执行的请求或历史费用。

curl \
  -X DELETE \
  -H "Authorization: Bearer YOUR_MANAGEMENT_TOKEN" \
  "https://creative-reasoning.com/api/v1/management/teams/TEAM_CODE/api-keys/API_KEY_ID"

HTTP 204 表示撤销成功，响应无正文。撤销 Key 不会撤销管理 Token；服务不再需要管理权限时，请管理员另行撤销该 Token。

若创建请求超时，先让有读权限的管理员核对结果，不要盲目重发。其余 Key 查询、修改、Reveal、预算删除及 Token 创建、修改、轮换方式见管理 API。

在控制台查看和设置

在控制台 API Key 页面选择目标团队，按标签或前缀找到 Key。设置用于标签、透支和消费预算；更多提供查看用量、复制 API Key ID 和撤销操作。普通用户只能管理自己的 Key，其他操作按账号权限开放。

标签与透支使用 保存设置，每项预算分别使用 保存预算。加载预算失败不代表未设置预算；请先重试，再修改配置。撤销不可恢复，也不会删除历史费用。

处理被拒绝的请求

先检查 HTTP 状态码和 Content-Type，再解析错误。将 application/json 解析为包含 error 字符串的对象。将 text/plain 视为诊断文本，不作为稳定错误码。

对于 JSON 请求，遇到 400 时修正语法，遇到 422 时修正字段类型或补齐必填字段，遇到 415 时修正 Content-Type。遇到 413 时缩小请求体。400 也可能表示 UUID 路径或业务规则无效。不要原样重试这些请求。额度与汇总的 422 含义不同，应按所调用操作的响应定义处理。

遇到 401，检查凭据类型、有效期和撤销状态；不要自动切换成 API Key 或 JWT。遇到 403，核对所需 scope。遇到 404，核对对象归属，仅对自己刚提交的调用做有限重试。遇到 422，缩小汇总范围；额度查询持续超限时联系管理员。遇到 429 或 503，按 Retry-After 退避并设置重试截止时间。