{ "openapi": "3.1.0", "info": { "title": "CR 管理 API 参考", "version": "2.0.0", "description": "本契约可匿名阅读；所有业务操作均要求凭据。按 HTTP 方法与路径计算，共 22 个操作：14 个自动化操作使用管理 Token，8 个 Token 生命周期操作使用管理员登录 JWT。两种凭据不能互换，也不能替代模型调用 API Key。\n\n## 凭据与权限\n\n团队 Token（scope_type=1）只管理一个团队的 API Key、预算、额度、用量与价格。组织 Token（scope_type=0，team_id=null）只查询本组织用量与价格，不能管理 API Key 或读取单 Key 额度。\n\n团队 Token 可授予 api_keys:read、api_keys:write、usage:read、usage:aggregate、pricing:read。组织 Token 仅允许后三项。每个 scope 独立，write 不包含 read，usage:read 不包含汇总。api_keys:write 包含返回完整 Key 的 Reveal 及移除预算限制，属于敏感权限。\n\nToken 生命周期要求登录 JWT。团队操作要求 TeamAdmin 及当前团队权限，组织操作要求本组织 OrgAdmin。Admin、SuperAdmin 可管理其他租户，签发的 Token 仍固定在目标租户。每次操作核验当前用户、组织和团队权限；有效角色不超过登录时与当前角色的较低值。变更组织或需要使用新授予的角色时须重新登录。 已签发的机器 Token 不随人员降权自动撤销。\n\n## 保存与轮换\n\nToken secret 仅创建时返回一次，没有找回、自动刷新或自行续期接口。程序从服务端秘密管理系统获取凭据，仅在 HTTPS Authorization: Bearer 头中传递。轮换顺序为创建新 Token、切换并验证、撤销旧 Token。页面不读取凭据，也不执行请求。\n\n## 限流与重试\n\n普通机器请求每 Token 每 60 秒最多 6000 查询单位，批量查账按输入 ID 数计数。额度与汇总另共享每分钟 241 单位/Token、960 单位/组织；额度每次 8 单位，汇总为 1+自然日数×范围权重（Key=1、团队=4、组织=8）。并发每 Token 1、每组织 2，服务容量也可能限制并发。\n\n401 表示凭据或会话失效；403 表示权限不足；404 可能是不存在、不可见或用量尚未可查。额度与汇总的 422 JSON 错误表示查询规模超限，不返回部分结果。429、503 的安全读取可按 Retry-After 有限退避重试。创建超时不应盲目重发，当前没有通用写入幂等键。撤销不回滚已执行的操作。\n\n## 错误响应格式\n\n业务错误使用 application/json，形状为 {error: string}。存量 JSON 请求还可能返回 text/plain：语法错误 400、字段类型错误或缺少必填字段 422、缺少或不支持 Content-Type 415、请求体超限 413。普通 UUID 路径解析失败返回 400 text/plain；额度接口的路径错误返回 400 JSON。客户端先读取 HTTP 状态码和 Content-Type，再解析错误；纯文本内容不是稳定的错误码，也不应据此自动重试。\n\n## 金额单位\n\n所有管理 API 的金额输入和输出使用 Credits（ℂ），与控制台一致。金额以精确十进制字符串表示，最多六位小数，不固定补零；单价按 Credits/单个计费单位返回，保留完整精度。例如 credits.after_discount 为 \"0.00553\" 表示折后费用为 0.00553 ℂ。预算和预支上限也使用 Credits。Token 数、计费数量、阶梯阈值和折扣分别按对应字段定义读取。成功响应通过 X-CRR-Credit-Unit: credits 标明金额单位；用量汇总的 schema_version 为 2。" }, "servers": [ { "url": "https://creative-reasoning.com", "description": "CR 管理 API" } ], "tags": [ { "name": "Management Tokens", "description": "使用登录 JWT 管理团队及组织 Token；所有操作核验当前权限。" }, { "name": "API Key Automation", "description": "使用最小 scope 自动化管理团队 API Key 与预算。" }, { "name": "Usage & Pricing", "description": "按 usage ID 查询最终费用，并读取团队折后模型价格。" } ], "paths": { "/api/v1/management/teams/{team_code}/api-keys/{api_key_id}/quota": { "parameters": [ { "$ref": "#/components/parameters/TeamCode" }, { "$ref": "#/components/parameters/ApiKeyId" } ], "get": { "tags": [ "API Key Automation" ], "operationId": "getManagedApiKeyQuota", "x-crr-required-scope": "api_keys:read", "summary": "查询 API Key 额度概览", "description": "仅限具有 api_keys:read 的团队 Token。无查询参数。返回同一观察时刻的余额、预支和预算快照，入账及对账存在延迟。每次消耗 8 个共享查询单位及 1 个通用单位。响应禁止缓存。只读请求可有限退避重试，规模超限返回 422 且不返回部分结果。", "security": [ { "managementTokenAuth": [] } ], "responses": { "200": { "description": "单 Key 额度快照。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyQuota" }, "example": { "api_key_id": "0198f000-0000-7000-8000-000000000001", "team_id": "0198f000-0000-7000-8000-000000000002", "unit": "credits", "observed_at": "2026-09-14T08:00:00Z", "consistency": "eventual", "available_credits": "3.5", "overdraft": { "enabled": true, "effective_enabled": true, "is_unlimited": false, "limit_credits": "5", "used_credits": "1.5", "remaining_credits": "3.5" }, "budgets": { "all_time": { "state": "not_configured", "enabled": false, "limit_credits": null, "used_credits": null, "remaining_credits": null, "starts_at": null, "window_days": null, "period_start": null, "period_end": null, "resets_at": null }, "windowed": { "state": "active", "enabled": true, "limit_credits": "10", "used_credits": "1.5", "remaining_credits": "8.5", "starts_at": "2026-09-01T08:00:00Z", "window_days": 7, "period_start": "2026-09-08T08:00:00Z", "period_end": "2026-09-15T08:00:00Z", "resets_at": "2026-09-15T08:00:00Z" } } } } }, "headers": { "X-CRR-Credit-Unit": { "$ref": "#/components/headers/CreditUnit" } } }, "400": { "description": "非法 UUID 或不支持的查询参数。", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } } } } } }, "401": { "$ref": "#/components/responses/InvalidManagementToken" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/ScopedNotFound" }, "422": { "description": "额度计算规模超限；不返回部分结果。", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "依赖故障或查询超时；Retry-After: 60。", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } } } } } } } } }, "/api/v1/organizations/{organization_id}/management-tokens": { "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Management Tokens" ], "operationId": "listOrganizationManagementTokens", "x-crr-minimum-role": "OrgAdmin", "summary": "列出组织级管理 Token", "description": "需要登录 JWT：本组织 OrgAdmin，或全局 Admin、SuperAdmin。仅允许 usage:read、usage:aggregate、pricing:read。secret 仅创建时返回，变更写入审计。 每次操作核验当前用户、组织和团队权限；有效角色不超过登录时与当前角色的较低值。变更组织或需要使用新授予的角色时须重新登录。 返回裸数组，包含已过期和已撤销 Token；status 不校验具体操作是否允许。", "security": [ { "userJwt": [] } ], "responses": { "200": { "description": "组织 Token 列表。", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ManagementToken" } }, "example": [ { "id": "018f1000-0000-7000-8000-000000000002", "name": "billing-service", "key_prefix": "crr_mt_018f1000", "scopes": [ "usage:read", "pricing:read" ], "created_by": "018f1000-0000-7000-8000-000000000006", "created_by_name": "Platform Operator", "expires_at": "2026-12-31T23:59:59+00:00", "revoked_at": null, "last_used_at": null, "created_at": "2026-08-28T08:00:00+00:00", "updated_at": "2026-08-28T08:00:00+00:00", "status": "active", "scope_type": 0, "organization_id": "018f1000-0000-7000-8000-000000000001", "team_id": null } ] } } }, "400": { "$ref": "#/components/responses/InvalidPath" }, "401": { "$ref": "#/components/responses/InvalidUserJwt" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "tags": [ "Management Tokens" ], "operationId": "createOrganizationManagementToken", "x-crr-minimum-role": "OrgAdmin", "summary": "创建组织级管理 Token", "description": "需要登录 JWT：本组织 OrgAdmin，或全局 Admin、SuperAdmin。仅允许 usage:read、usage:aggregate、pricing:read。secret 仅创建时返回，变更写入审计。 每次操作核验当前用户、组织和团队权限；有效角色不超过登录时与当前角色的较低值。变更组织或需要使用新授予的角色时须重新登录。", "security": [ { "userJwt": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationManagementTokenRequest" }, "example": { "name": "billing-service", "scopes": [ "usage:read", "pricing:read" ], "expires_at": "2026-12-31T23:59:59+00:00" } } } }, "responses": { "201": { "description": "Token 已创建；立即保存 secret。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementTokenCreated" }, "example": { "id": "018f1000-0000-7000-8000-000000000002", "name": "billing-service", "key_prefix": "crr_mt_018f1000", "scopes": [ "usage:read", "pricing:read" ], "created_by": "018f1000-0000-7000-8000-000000000006", "created_by_name": "Platform Operator", "expires_at": "2026-12-31T23:59:59+00:00", "revoked_at": null, "last_used_at": null, "created_at": "2026-08-28T08:00:00+00:00", "updated_at": "2026-08-28T08:00:00+00:00", "status": "active", "secret": "crr_mt__", "scope_type": 0, "organization_id": "018f1000-0000-7000-8000-000000000001", "team_id": null } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/InvalidUserJwt" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/RequestBodyTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/InvalidJsonData" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/organizations/{organization_id}/management-tokens/{token_id}": { "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/TokenId" } ], "patch": { "tags": [ "Management Tokens" ], "operationId": "updateOrganizationManagementToken", "x-crr-minimum-role": "OrgAdmin", "summary": "修改组织级管理 Token", "description": "需要登录 JWT：本组织 OrgAdmin，或全局 Admin、SuperAdmin。仅允许 usage:read、usage:aggregate、pricing:read。secret 仅创建时返回，变更写入审计。 每次操作核验当前用户、组织和团队权限；有效角色不超过登录时与当前角色的较低值。变更组织或需要使用新授予的角色时须重新登录。 scopes 替换完整集合。expires_at 省略不变，null 清除；已撤销 Token 不能修改。", "security": [ { "userJwt": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationManagementTokenRequest" }, "example": { "scopes": [ "usage:read", "pricing:read" ], "expires_at": "2026-12-31T23:59:59+00:00" } } } }, "responses": { "200": { "description": "更新后的 Token 元数据。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementToken" }, "example": { "id": "018f1000-0000-7000-8000-000000000002", "name": "billing-service", "key_prefix": "crr_mt_018f1000", "scopes": [ "usage:read", "pricing:read" ], "created_by": "018f1000-0000-7000-8000-000000000006", "created_by_name": "Platform Operator", "expires_at": "2026-12-31T23:59:59+00:00", "revoked_at": null, "last_used_at": null, "created_at": "2026-08-28T08:00:00+00:00", "updated_at": "2026-08-28T08:00:00+00:00", "status": "active", "scope_type": 0, "organization_id": "018f1000-0000-7000-8000-000000000001", "team_id": null } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/InvalidUserJwt" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/RequestBodyTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/InvalidJsonData" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "tags": [ "Management Tokens" ], "operationId": "revokeOrganizationManagementToken", "x-crr-minimum-role": "OrgAdmin", "summary": "撤销组织级管理 Token", "description": "需要登录 JWT：本组织 OrgAdmin，或全局 Admin、SuperAdmin。仅允许 usage:read、usage:aggregate、pricing:read。secret 仅创建时返回，变更写入审计。 每次操作核验当前用户、组织和团队权限；有效角色不超过登录时与当前角色的较低值。变更组织或需要使用新授予的角色时须重新登录。 重复撤销仍返回 204；撤销不取消在途操作。", "security": [ { "userJwt": [] } ], "responses": { "204": { "description": "已撤销。" }, "400": { "$ref": "#/components/responses/InvalidPath" }, "401": { "$ref": "#/components/responses/InvalidUserJwt" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/management/usage/summary": { "get": { "tags": [ "Usage & Pricing" ], "operationId": "getManagementUsageSummary", "x-crr-required-scope": "usage:aggregate", "summary": "查询区间账单用量汇总", "description": "独立要求 usage:aggregate。Key 或团队查询最多 31 个自然日，组织全量最多 30 日；RFC3339 时间还受实际跨度限制。未知或重复参数返回 400。六个 token 维度只统计已完成文本账单，不代表完整模型用量。缺失项按零汇总，非法项跳过并计数；不能据此认定未记录的用量为零。费用包括所有请求类型，请求数排除轮询。总量与当前页基于同一观察时刻，不同页可能变化。最多 250000 条候选记录（模型及类型筛选前）、100000 组、1000000 个可选计费项；超限返回 422，不截断为完整结果。", "security": [ { "managementTokenAuth": [] } ], "parameters": [ { "name": "start", "in": "query", "required": true, "description": "必填 RFC3339 或 YYYY-MM-DD，裸日期使用当地零点。", "schema": { "type": "string" } }, { "name": "end", "in": "query", "required": false, "description": "默认请求接收时刻。RFC3339 为排他上界；裸日期包含完整自然日。", "schema": { "type": "string" } }, { "name": "timezone", "in": "query", "required": false, "description": "日期解释和分桶所用的 IANA 时区。", "schema": { "type": "string", "default": "Asia/Shanghai" } }, { "name": "team_code", "in": "query", "required": false, "description": "可选团队编号（如 T-TU214G），从控制台复制。不是 UUID。团队 Token 省略时使用绑定团队，不能选择其他团队；组织 Token 可查本组织已移除团队的历史。", "schema": { "type": "string" }, "example": "T-TU214G" }, { "name": "api_key_id", "in": "query", "required": false, "description": "API Key 资源的 UUID。在 API Key 列表的目标行选择“更多 → 复制 API Key ID”，或从 GET /api/v1/management/teams/{team_code}/api-keys 响应项的 id 获取（需 api_keys:read）。不是 API Key 明文、前缀或管理 Token；不能用于调用模型。 同时受 Token 范围和 team_code 限定，撤销不抹去历史。", "schema": { "type": "string", "format": "uuid" } }, { "name": "model_id", "in": "query", "required": false, "description": "账单响应中 model.id 的 UUID；模型停用不抹去历史。", "schema": { "type": "string", "format": "uuid" } }, { "name": "request_type", "in": "query", "required": false, "description": "已保存的请求类型。", "schema": { "type": "string", "enum": [ "chat", "stream", "responses", "embedding", "rerank", "image_gen", "video_gen", "passthrough", "poll", "metered" ] } }, { "name": "group_by", "in": "query", "required": false, "description": "缺省只返回总量。UUID 和类型顺序固定，时间桶按开始时刻排序。", "schema": { "type": "string", "enum": [ "key", "team", "model", "request_type", "time" ] } }, { "name": "granularity", "in": "query", "required": false, "description": "仅 group_by=time 时有效，默认 day，不返回空桶。", "schema": { "type": "string", "enum": [ "hour", "day" ] } }, { "name": "include_billing_dimensions", "in": "query", "required": false, "description": "包含媒体、meter、Poll 的全部账单维度数量，不返回价格或成本。", "schema": { "type": "boolean", "default": false } }, { "name": "page", "in": "query", "required": false, "description": "仅分组时有效，0 变为 1，空页保留真实 total。", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "仅分组时有效，归一化到 1–200。", "schema": { "type": "integer", "minimum": 0, "default": 50 } } ], "responses": { "200": { "description": "账单用量汇总。", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "Vary": { "schema": { "type": "string", "const": "Authorization" } }, "X-CRR-Credit-Unit": { "$ref": "#/components/headers/CreditUnit" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageSummary" }, "example": { "schema_version": 2, "window": { "start": "2026-08-30T16:00:00Z", "end": "2026-08-31T16:00:00Z", "end_exclusive": true, "timezone": "Asia/Shanghai" }, "scope": { "organization_id": "018f1000-0000-7000-8000-000000000001", "team_id": "018f1000-0000-7000-8000-000000000003", "api_key_id": null }, "data": { "basis": "persisted_request_logs", "snapshot_observed_at": "2026-09-14T02:00:00Z", "aggregation_version": 1, "source": "raw" }, "totals": { "request_count": "1", "pending_request_count": "0", "credits": { "before_discount": "0.05", "after_discount": "0.0375" }, "tokens": { "basis": "stored_billing_items", "scope": "text_request_types", "input": { "prompt_tokens": "9007199254740993", "cache_read_tokens": "0", "cache_write_tokens": "0", "audio_tokens": "0" }, "output": { "completion_tokens": "2", "audio_tokens": "0" }, "invalid_item_count": "0" } } } } } }, "400": { "description": "参数或时间窗口无效。", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "Vary": { "schema": { "type": "string", "const": "Authorization" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Token 无效、过期、撤销，或租户已移除。", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "Vary": { "schema": { "type": "string", "const": "Authorization" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "缺少 usage:aggregate。", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "Vary": { "schema": { "type": "string", "const": "Authorization" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "资源不存在或不可见。", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "Vary": { "schema": { "type": "string", "const": "Authorization" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "查询规模超限；缩小范围后重试。", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "Vary": { "schema": { "type": "string", "const": "Authorization" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "超过频率或并发限制。", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "Vary": { "schema": { "type": "string", "const": "Authorization" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "example": 60 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "服务错误。", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "Vary": { "schema": { "type": "string", "const": "Authorization" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "查询超时或暂不可用。", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "Vary": { "schema": { "type": "string", "const": "Authorization" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "example": 60 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/teams/{team_code}/management-tokens": { "parameters": [ { "$ref": "#/components/parameters/TeamCode" } ], "get": { "tags": [ "Management Tokens" ], "operationId": "listTeamManagementTokens", "x-crr-minimum-role": "TeamAdmin", "summary": "列出团队管理 Token", "description": "要求交互式用户 JWT、TeamAdmin 或更高角色，并受团队作用域限制。响应从不返回 Token 原文。 每次操作核验当前用户、组织和团队权限；有效角色不超过登录时与当前角色的较低值。变更组织或需要使用新授予的角色时须重新登录。 返回裸数组，包含已过期和已撤销 Token；status 不校验具体操作是否允许。", "security": [ { "userJwt": [] } ], "responses": { "200": { "description": "团队 Token 列表。", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ManagementToken" } }, "example": [ { "id": "018f1000-0000-7000-8000-000000000002", "name": "billing-service", "key_prefix": "crr_mt_018f1000", "scopes": [ "usage:read", "pricing:read" ], "created_by": "018f1000-0000-7000-8000-000000000006", "created_by_name": "Platform Operator", "expires_at": "2026-12-31T23:59:59+00:00", "revoked_at": null, "last_used_at": null, "created_at": "2026-08-28T08:00:00+00:00", "updated_at": "2026-08-28T08:00:00+00:00", "status": "active", "scope_type": 1, "organization_id": "018f1000-0000-7000-8000-000000000001", "team_id": "018f1000-0000-7000-8000-000000000003" } ] } } }, "400": { "$ref": "#/components/responses/InvalidPath" }, "401": { "$ref": "#/components/responses/InvalidUserJwt" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "tags": [ "Management Tokens" ], "operationId": "createTeamManagementToken", "x-crr-minimum-role": "TeamAdmin", "summary": "创建团队管理 Token", "description": "要求交互式用户 JWT、TeamAdmin 或更高角色。`secret` 仅在本次 201 响应中返回，之后无法找回。 每次操作核验当前用户、组织和团队权限；有效角色不超过登录时与当前角色的较低值。变更组织或需要使用新授予的角色时须重新登录。", "security": [ { "userJwt": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateManagementTokenRequest" }, "example": { "name": "billing-service", "scopes": [ "usage:read", "pricing:read" ], "expires_at": "2026-12-31T23:59:59+00:00" } } } }, "responses": { "201": { "description": "Token 已创建；立即保存 secret。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementTokenCreated" }, "example": { "id": "018f1000-0000-7000-8000-000000000002", "name": "billing-service", "key_prefix": "crr_mt_018f1000", "scopes": [ "usage:read", "pricing:read" ], "created_by": "018f1000-0000-7000-8000-000000000006", "created_by_name": "Platform Operator", "expires_at": "2026-12-31T23:59:59+00:00", "revoked_at": null, "last_used_at": null, "created_at": "2026-08-28T08:00:00+00:00", "updated_at": "2026-08-28T08:00:00+00:00", "status": "active", "secret": "crr_mt__", "scope_type": 1, "organization_id": "018f1000-0000-7000-8000-000000000001", "team_id": "018f1000-0000-7000-8000-000000000003" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/InvalidUserJwt" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/RequestBodyTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/InvalidJsonData" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/teams/{team_code}/management-tokens/{token_id}": { "parameters": [ { "$ref": "#/components/parameters/TeamCode" }, { "$ref": "#/components/parameters/TokenId" } ], "patch": { "tags": [ "Management Tokens" ], "operationId": "updateTeamManagementToken", "x-crr-minimum-role": "TeamAdmin", "summary": "更新团队管理 Token", "description": "更新名称、scope 或过期时间并立即生效。`expires_at: null` 清除过期时间；已撤销 Token 不能更新。 每次操作核验当前用户、组织和团队权限；有效角色不超过登录时与当前角色的较低值。变更组织或需要使用新授予的角色时须重新登录。", "security": [ { "userJwt": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateManagementTokenRequest" }, "example": { "scopes": [ "usage:read", "pricing:read" ], "expires_at": "2026-12-31T23:59:59+00:00" } } } }, "responses": { "200": { "description": "更新后的 Token 元数据。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementToken" }, "example": { "id": "018f1000-0000-7000-8000-000000000002", "name": "billing-service", "key_prefix": "crr_mt_018f1000", "scopes": [ "usage:read", "pricing:read" ], "created_by": "018f1000-0000-7000-8000-000000000006", "created_by_name": "Platform Operator", "expires_at": "2026-12-31T23:59:59+00:00", "revoked_at": null, "last_used_at": null, "created_at": "2026-08-28T08:00:00+00:00", "updated_at": "2026-08-28T08:00:00+00:00", "status": "active", "scope_type": 1, "organization_id": "018f1000-0000-7000-8000-000000000001", "team_id": "018f1000-0000-7000-8000-000000000003" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/InvalidUserJwt" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/RequestBodyTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/InvalidJsonData" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "tags": [ "Management Tokens" ], "operationId": "revokeTeamManagementToken", "x-crr-minimum-role": "TeamAdmin", "summary": "撤销团队管理 Token", "description": "撤销立即生效；重复撤销仍返回 204。 每次操作核验当前用户、组织和团队权限；有效角色不超过登录时与当前角色的较低值。变更组织或需要使用新授予的角色时须重新登录。", "security": [ { "userJwt": [] } ], "responses": { "204": { "description": "已撤销。" }, "400": { "$ref": "#/components/responses/InvalidPath" }, "401": { "$ref": "#/components/responses/InvalidUserJwt" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/management/teams/{team_code}/api-keys": { "parameters": [ { "$ref": "#/components/parameters/TeamCode" } ], "get": { "tags": [ "API Key Automation" ], "operationId": "listManagedApiKeys", "x-crr-required-scope": "api_keys:read", "summary": "列出团队 API Key", "description": "要求 `api_keys:read`。只返回 Token 所属团队的 API Key。 返回未撤销 Key 的裸数组，无分页；GET 详情仍可读取已撤销 Key。", "security": [ { "managementTokenAuth": [] } ], "responses": { "200": { "description": "API Key 列表。", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedApiKey" } }, "example": [ { "id": "018f1000-0000-7000-8000-000000000003", "team_id": "018f1000-0000-7000-8000-000000000001", "owner_id": null, "owner_email": null, "key_prefix": "crr_ab12cd34", "label": "batch-render-worker", "balance": "0", "available_credits": "60", "consumed_credits": "4.2", "original_consumed_credits": "5.25", "discount_savings_credits": "1.05", "overdraft_enabled": false, "overdraft_limit": "0", "effective_overdraft_enabled": false, "can_configure_overdraft": true, "overdraft_unavailable_reason": null, "budgets": [] } ] } }, "headers": { "X-CRR-Credit-Unit": { "$ref": "#/components/headers/CreditUnit" } } }, "400": { "$ref": "#/components/responses/InvalidPath" }, "401": { "$ref": "#/components/responses/InvalidManagementToken" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/ScopedNotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "tags": [ "API Key Automation" ], "operationId": "createManagedApiKey", "x-crr-required-scope": "api_keys:write", "summary": "创建团队 API Key", "description": "要求 `api_keys:write`。路径中的团队编号（team_code）决定归属；创建操作在本次响应返回完整 API Key，之后重新读取必须使用单独的审计 Reveal 接口。 管理 Token 创建的 Key 无人员 owner。若不需要预支，显式发送 overdraft_enabled=false；默认值见请求字段。创建与设置预算不是原子操作。", "security": [ { "managementTokenAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateManagedApiKeyRequest" }, "example": { "label": "batch-render-worker" } } } }, "responses": { "201": { "description": "API Key 已创建。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedApiKeyCreated" }, "example": { "id": "018f1000-0000-7000-8000-000000000003", "key": "crr_", "key_prefix": "crr_ab12cd34" } } }, "headers": { "X-CRR-Credit-Unit": { "$ref": "#/components/headers/CreditUnit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/InvalidManagementToken" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/ScopedNotFound" }, "413": { "$ref": "#/components/responses/RequestBodyTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/InvalidJsonData" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/management/teams/{team_code}/api-keys/{api_key_id}": { "parameters": [ { "$ref": "#/components/parameters/TeamCode" }, { "$ref": "#/components/parameters/ApiKeyId" } ], "get": { "tags": [ "API Key Automation" ], "operationId": "getManagedApiKey", "x-crr-required-scope": "api_keys:read", "summary": "读取团队 API Key", "description": "要求 `api_keys:read`。跨团队 ID 与不存在资源统一返回 404。", "security": [ { "managementTokenAuth": [] } ], "responses": { "200": { "description": "API Key 元数据与余额摘要。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedApiKey" }, "example": { "id": "018f1000-0000-7000-8000-000000000003", "team_id": "018f1000-0000-7000-8000-000000000001", "owner_id": null, "owner_email": null, "key_prefix": "crr_ab12cd34", "label": "batch-render-worker", "balance": "0", "available_credits": "60", "consumed_credits": "4.2", "original_consumed_credits": "5.25", "discount_savings_credits": "1.05", "overdraft_enabled": false, "overdraft_limit": "0", "effective_overdraft_enabled": false, "can_configure_overdraft": true, "overdraft_unavailable_reason": null, "budgets": [] } } }, "headers": { "X-CRR-Credit-Unit": { "$ref": "#/components/headers/CreditUnit" } } }, "400": { "$ref": "#/components/responses/InvalidPath" }, "401": { "$ref": "#/components/responses/InvalidManagementToken" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/ScopedNotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "tags": [ "API Key Automation" ], "operationId": "updateManagedApiKey", "x-crr-required-scope": "api_keys:write", "summary": "更新团队 API Key", "description": "要求 `api_keys:write`。可修改标签与透支设置。省略或 null 不修改字段，空字符串清除标签。不能更改团队、owner 或直接修改余额。", "security": [ { "managementTokenAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateManagedApiKeyRequest" }, "example": { "label": "batch-render-worker-v2" } } } }, "responses": { "200": { "description": "更新后的 API Key。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedApiKey" }, "example": { "id": "018f1000-0000-7000-8000-000000000003", "team_id": "018f1000-0000-7000-8000-000000000001", "owner_id": null, "owner_email": null, "key_prefix": "crr_ab12cd34", "label": "batch-render-worker-v2", "balance": "0", "available_credits": "60", "consumed_credits": "4.2", "original_consumed_credits": "5.25", "discount_savings_credits": "1.05", "overdraft_enabled": false, "overdraft_limit": "0", "effective_overdraft_enabled": false, "can_configure_overdraft": true, "overdraft_unavailable_reason": null, "budgets": [] } } }, "headers": { "X-CRR-Credit-Unit": { "$ref": "#/components/headers/CreditUnit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/InvalidManagementToken" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/ScopedNotFound" }, "413": { "$ref": "#/components/responses/RequestBodyTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/InvalidJsonData" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "tags": [ "API Key Automation" ], "operationId": "revokeManagedApiKey", "x-crr-required-scope": "api_keys:write", "summary": "撤销团队 API Key", "description": "要求 `api_keys:write`。撤销后该 API Key 不能再调用模型。 重复撤销仍返回 204，但可能重复审计。撤销不取消在途请求或历史费用，也不撤销管理 Token。", "security": [ { "managementTokenAuth": [] } ], "responses": { "204": { "description": "已撤销。", "headers": { "X-CRR-Credit-Unit": { "$ref": "#/components/headers/CreditUnit" } } }, "400": { "$ref": "#/components/responses/InvalidPath" }, "401": { "$ref": "#/components/responses/InvalidManagementToken" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/ScopedNotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/management/teams/{team_code}/api-keys/{api_key_id}/reveal": { "parameters": [ { "$ref": "#/components/parameters/TeamCode" }, { "$ref": "#/components/parameters/ApiKeyId" } ], "get": { "tags": [ "API Key Automation" ], "operationId": "revealManagedApiKey", "x-crr-required-scope": "api_keys:write", "summary": "读取完整 API Key", "description": "要求 `api_keys:write`，属于高敏感操作并写入审计日志。旧 Key 可能返回 `key: null`。 key=null 表示没有可返回的完整值，不是空 Key。客户端不得缓存或记录返回的凭据。", "security": [ { "managementTokenAuth": [] } ], "responses": { "200": { "description": "完整 API Key。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevealApiKeyResponse" }, "example": { "key": "crr_" } } }, "headers": { "X-CRR-Credit-Unit": { "$ref": "#/components/headers/CreditUnit" } } }, "400": { "$ref": "#/components/responses/InvalidPath" }, "401": { "$ref": "#/components/responses/InvalidManagementToken" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/ScopedNotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/management/teams/{team_code}/api-keys/{api_key_id}/budgets": { "parameters": [ { "$ref": "#/components/parameters/TeamCode" }, { "$ref": "#/components/parameters/ApiKeyId" } ], "get": { "tags": [ "API Key Automation" ], "operationId": "listManagedApiKeyBudgets", "x-crr-required-scope": "api_keys:read", "summary": "列出 API Key 预算", "description": "要求 api_keys:read。返回已配置预算的裸数组，最多两项；未配置返回 []。消费为当前已记录值，不保证所有请求均已入账。remaining、is_blocked 与 quota 状态语义不同，详见响应字段。", "security": [ { "managementTokenAuth": [] } ], "responses": { "200": { "description": "预算列表。", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyBudget" } }, "example": [] } }, "headers": { "X-CRR-Credit-Unit": { "$ref": "#/components/headers/CreditUnit" } } }, "400": { "$ref": "#/components/responses/InvalidPath" }, "401": { "$ref": "#/components/responses/InvalidManagementToken" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/ScopedNotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/management/teams/{team_code}/api-keys/{api_key_id}/budgets/{budget_type}": { "parameters": [ { "$ref": "#/components/parameters/TeamCode" }, { "$ref": "#/components/parameters/ApiKeyId" }, { "$ref": "#/components/parameters/BudgetType" } ], "put": { "tags": [ "API Key Automation" ], "operationId": "upsertManagedApiKeyBudget", "x-crr-required-scope": "api_keys:write", "summary": "创建或更新 API Key 预算", "description": "要求 `api_keys:write`。`all_time` 不接受 window_days；`windowed` 要求 window_days ≥ 1。 每次必须发送 amount；starts_at 和 is_enabled 的省略行为区分首次设置与更新。修改起算点会改变统计范围。配置成功不保证策略已传播完成。", "security": [ { "managementTokenAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertApiKeyBudgetRequest" }, "examples": { "windowed": { "value": { "amount": "50", "window_days": 30, "is_enabled": true } }, "all_time": { "value": { "amount": "50", "is_enabled": true } } } } } }, "responses": { "200": { "description": "预算当前状态。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyBudget" }, "example": { "budget_type": "windowed", "amount": "50", "window_days": 30, "starts_at": "2026-08-28T08:00:00+00:00", "is_enabled": true, "current_consumed": "4.2", "remaining": "45.8", "segment_start": "2026-08-28T08:00:00+00:00", "segment_end": "2026-09-27T08:00:00Z", "is_blocked": false } } }, "headers": { "X-CRR-Credit-Unit": { "$ref": "#/components/headers/CreditUnit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/InvalidManagementToken" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/ScopedNotFound" }, "413": { "$ref": "#/components/responses/RequestBodyTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/InvalidJsonData" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "tags": [ "API Key Automation" ], "operationId": "deleteManagedApiKeyBudget", "x-crr-required-scope": "api_keys:write", "summary": "删除 API Key 预算", "description": "要求 `api_keys:write`。 删除的是消费限制，不是欠款或账单。预算不存在时返回 404；非法 budget_type 返回 400。", "security": [ { "managementTokenAuth": [] } ], "responses": { "204": { "description": "已删除。", "headers": { "X-CRR-Credit-Unit": { "$ref": "#/components/headers/CreditUnit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/InvalidManagementToken" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/ScopedNotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/management/usage/{usage_id}": { "parameters": [ { "$ref": "#/components/parameters/UsageId" } ], "get": { "tags": [ "Usage & Pricing" ], "operationId": "getManagementRequestUsage", "x-crr-required-scope": "usage:read", "summary": "按 usage ID 查询用量与费用", "description": "要求 usage:read。使用模型响应头 x-cr-usage-id 查询稳定的账单记录。x-cr-request-id 只标识当次 HTTP 请求，不能用轮询或重试的请求 ID 替代用量 ID。新记录可能短暂返回 404；billing_status=pending 时带 Retry-After: 1，credits 为 null。final 不表示生成成功。仅返回用量 ID、账单状态、创建时间、计费维度数量和折前/折后 Credits。金额单位为 Credits（ℂ），成功响应通过 X-CRR-Credit-Unit: credits 标明该单位。final 状态下，credits.after_discount 为本次调用的最终费用。", "security": [ { "managementTokenAuth": [] } ], "responses": { "200": { "description": "用量与费用状态。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" }, "examples": { "final": { "value": { "usage_id": "018f1000-0000-7000-8000-000000000004", "billing_status": "final", "created_at": "2026-08-28T08:00:00+00:00", "usage_items": [ { "name": "input:prompt_tokens", "usage": 1000 }, { "name": "output:completion_tokens", "usage": 200 } ], "credits": { "before_discount": "0.0525", "after_discount": "0.042" } } }, "pending": { "value": { "usage_id": "018f1000-0000-7000-8000-000000000098", "billing_status": "pending", "created_at": "2026-08-28T08:00:00+00:00", "usage_items": [], "credits": null } } } } }, "headers": { "Retry-After": { "description": "仅 pending 时建议等待秒数。", "schema": { "type": "integer", "minimum": 1 } }, "X-CRR-Credit-Unit": { "$ref": "#/components/headers/CreditUnit" } } }, "400": { "$ref": "#/components/responses/InvalidPath" }, "401": { "$ref": "#/components/responses/InvalidManagementToken" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/ScopedNotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/management/usage/batch": { "post": { "tags": [ "Usage & Pricing" ], "operationId": "batchGetManagementRequestUsage", "x-crr-required-scope": "usage:read", "summary": "批量查询用量与费用", "description": "要求 usage:read。正文只接受 usage_ids：1–100 个来自 x-cr-usage-id 的 UUID；保留输入顺序和重复项。未知字段返回 422 text/plain。不存在或超出 Token 租户范围时 lookup_status 为 not_found、usage 为 null。found 项使用与单条查询相同的精简账单。逐项检查 billing_status；批量 HTTP 200 不代表每项已计费完成。重复 ID 也消耗限流单位。", "security": [ { "managementTokenAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchUsageRequest" }, "example": { "usage_ids": [ "018f1000-0000-7000-8000-000000000004" ] } } } }, "responses": { "200": { "description": "逐项查询结果。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchUsageResponse" }, "examples": { "mixed": { "value": { "items": [ { "usage_id": "018f1000-0000-7000-8000-000000000004", "lookup_status": "found", "usage": { "usage_id": "018f1000-0000-7000-8000-000000000004", "billing_status": "final", "created_at": "2026-08-28T08:00:00+00:00", "usage_items": [ { "name": "input:prompt_tokens", "usage": 1000 }, { "name": "output:completion_tokens", "usage": 200 } ], "credits": { "before_discount": "0.0525", "after_discount": "0.042" } } }, { "usage_id": "018f1000-0000-7000-8000-000000000004", "lookup_status": "found", "usage": { "usage_id": "018f1000-0000-7000-8000-000000000004", "billing_status": "final", "created_at": "2026-08-28T08:00:00+00:00", "usage_items": [ { "name": "input:prompt_tokens", "usage": 1000 }, { "name": "output:completion_tokens", "usage": 200 } ], "credits": { "before_discount": "0.0525", "after_discount": "0.042" } } }, { "usage_id": "018f1000-0000-7000-8000-000000000099", "lookup_status": "not_found", "usage": null }, { "usage_id": "018f1000-0000-7000-8000-000000000098", "lookup_status": "found", "usage": { "usage_id": "018f1000-0000-7000-8000-000000000098", "billing_status": "pending", "created_at": "2026-08-28T08:00:00+00:00", "usage_items": [], "credits": null } } ] } } } } }, "headers": { "X-CRR-Credit-Unit": { "$ref": "#/components/headers/CreditUnit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/InvalidManagementToken" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "413": { "$ref": "#/components/responses/RequestBodyTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/InvalidJsonData" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/management/teams/{team_code}/models/pricing": { "parameters": [ { "$ref": "#/components/parameters/TeamCode" } ], "get": { "tags": [ "Usage & Pricing" ], "operationId": "listManagementModelPricing", "x-crr-required-scope": "pricing:read", "summary": "查询团队模型有效价格", "description": "要求 pricing:read。返回模型名称、标价、组织折扣和有效价格，不含未上架模型。结果中的模型不一定对某个 API Key 可用。 返回裸数组，无分页。团队 Token 只查绑定团队，组织 Token 可选择本组织的有效团队。价格是当前值，不用于重算历史账单。", "security": [ { "managementTokenAuth": [] } ], "responses": { "200": { "description": "团队有效价格。", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EffectiveModelPricing" } }, "example": [ { "name": "MODEL_NAME", "metadata": { "display_name": "Model display name", "category": "llm", "tags": [ "chat" ] }, "effective_pricing": { "input:prompt_tokens": "0.00000004", "output:completion_tokens": "0.00000012" }, "pricing": { "input:prompt_tokens": "0.00000005", "output:completion_tokens": "0.00000015" }, "discount": 8000 } ] } }, "headers": { "X-CRR-Credit-Unit": { "$ref": "#/components/headers/CreditUnit" } } }, "400": { "$ref": "#/components/responses/InvalidPath" }, "401": { "$ref": "#/components/responses/InvalidManagementToken" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/ScopedNotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "components": { "securitySchemes": { "userJwt": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "通过登录/SSO 获取的交互式用户 JWT，仅用于 Token 生命周期接口。" }, "managementTokenAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "CRR Management Token", "description": "以 `crr_mt_` 开头的团队或组织管理 Token，仅发送到 `/api/v1/management/*`。" } }, "parameters": { "TeamCode": { "name": "team_code", "in": "path", "required": true, "description": "团队编号，例如 T-TU214G。从控制台团队标题旁复制纯编号。不是组织编号或团队 UUID；机器接口不接受 UUID。团队 Token 仅限绑定团队，组织 Token 仅限本组织。JWT Token 生命周期为兼容既有控制台客户端，仍额外接受团队 UUID。", "schema": { "type": "string" }, "example": "T-TU214G" }, "TokenId": { "name": "token_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "ApiKeyId": { "name": "api_key_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "API Key 资源的 UUID。在 API Key 列表的目标行选择“更多 → 复制 API Key ID”，或从 GET /api/v1/management/teams/{team_code}/api-keys 响应项的 id 获取（需 api_keys:read）。不是 API Key 明文、前缀或管理 Token；不能用于调用模型。" }, "BudgetType": { "name": "budget_type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "all_time", "windowed" ] } }, "UsageId": { "name": "usage_id", "in": "path", "required": true, "description": "账单 UUID，从模型响应头 x-cr-usage-id 获取。不要使用轮询请求的 x-cr-request-id、任务状态字段或 API Key ID。", "schema": { "type": "string", "format": "uuid" } } }, "schemas": { "ApiKeyQuota": { "type": "object", "additionalProperties": false, "required": [ "api_key_id", "team_id", "unit", "observed_at", "consistency", "available_credits", "overdraft", "budgets" ], "properties": { "api_key_id": { "type": "string", "format": "uuid" }, "team_id": { "type": "string", "format": "uuid" }, "unit": { "type": "string", "const": "credits" }, "observed_at": { "type": "string", "format": "date-time" }, "consistency": { "type": "string", "const": "eventual" }, "available_credits": { "$ref": "#/components/schemas/CreditAmount" }, "overdraft": { "$ref": "#/components/schemas/ApiKeyOverdraftQuota" }, "budgets": { "type": "object", "additionalProperties": false, "required": [ "all_time", "windowed" ], "properties": { "all_time": { "$ref": "#/components/schemas/ApiKeyQuotaBudget" }, "windowed": { "$ref": "#/components/schemas/ApiKeyQuotaBudget" } } } }, "description": "Credits 快照，不是模型 token 数或可调用判定。observed_at 是计算时间，不是入账水位。available_credits 为有效可访问订单余额加已对账 Key 净余额，可为负且不独占，不包含未来预支。" }, "ApiKeyOverdraftQuota": { "type": "object", "additionalProperties": false, "required": [ "enabled", "effective_enabled", "is_unlimited", "limit_credits", "used_credits", "remaining_credits" ], "properties": { "enabled": { "type": "boolean" }, "effective_enabled": { "type": "boolean" }, "is_unlimited": { "type": "boolean" }, "limit_credits": { "anyOf": [ { "$ref": "#/components/schemas/CreditAmount" }, { "type": "null" } ] }, "used_credits": { "$ref": "#/components/schemas/CreditAmount" }, "remaining_credits": { "anyOf": [ { "$ref": "#/components/schemas/CreditAmount" }, { "type": "null" } ] } }, "description": "enabled 是 Key 配置，effective_enabled 是三级开关交集，不代表父级配额未耗尽。used=max(-已对账净余额,0)。无限时 limit 为 null。remaining 在开关不生效时为 0；生效且无限时为 null；否则 max(limit-used,0)。关闭或周期重置不清欠款。" }, "ApiKeyQuotaBudget": { "type": "object", "additionalProperties": false, "required": [ "state", "enabled", "limit_credits", "used_credits", "remaining_credits", "starts_at", "window_days", "period_start", "period_end", "resets_at" ], "properties": { "state": { "type": "string", "enum": [ "not_configured", "disabled", "not_started", "active", "exhausted" ], "description": "not_configured=未配置，disabled=停用，not_started=尚未开始，active=启用且有余额，exhausted=启用且预算耗尽。仅描述该预算，不代表最终调用许可。" }, "enabled": { "type": "boolean" }, "limit_credits": { "anyOf": [ { "$ref": "#/components/schemas/CreditAmount" }, { "type": "null" } ] }, "used_credits": { "anyOf": [ { "$ref": "#/components/schemas/CreditAmount" }, { "type": "null" } ] }, "remaining_credits": { "anyOf": [ { "$ref": "#/components/schemas/CreditAmount" }, { "type": "null" } ] }, "starts_at": { "type": [ "string", "null" ], "format": "date-time" }, "window_days": { "type": [ "integer", "null" ], "minimum": 1 }, "period_start": { "type": [ "string", "null" ], "format": "date-time" }, "period_end": { "type": [ "string", "null" ], "format": "date-time" }, "resets_at": { "type": [ "string", "null" ], "format": "date-time" } }, "description": "按消费记账时间统计模型调用及计量支出，不是请求发生时间报表。未配置时金额为 null；未开始时 used_credits 为 0；停用预算仍报告已记录支出。仅启用且已开始时 remaining_credits=max(limit_credits-used_credits,0)，否则为 null。窗口从 starts_at 起每 N×86400 秒重置，不按自然月或当地午夜重置。总额预算永不自动重置；只有启用且已开始的周期预算 resets_at=period_end，其余为 null。重置不充值、不清除欠款。" }, "UsageSummaryTokens": { "type": "object", "additionalProperties": false, "properties": { "basis": { "const": "stored_billing_items" }, "scope": { "const": "text_request_types" }, "input": { "type": "object", "additionalProperties": false, "properties": { "prompt_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "cache_read_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "cache_write_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "audio_tokens": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "prompt_tokens", "cache_read_tokens", "cache_write_tokens", "audio_tokens" ] }, "output": { "type": "object", "additionalProperties": false, "properties": { "completion_tokens": { "type": "string", "pattern": "^[0-9]+$" }, "audio_tokens": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "completion_tokens", "audio_tokens" ] }, "invalid_item_count": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "basis", "scope", "input", "output", "invalid_item_count" ], "description": "账单记录中的文本 token 数，均为非负整数字符串，不折算成 Credits。各维度可能重叠，不能相加当作总 token。只覆盖 chat、stream、responses、embedding、rerank 的已完成账单；不提供用量完整度百分比。" }, "UsageSummaryDimensions": { "type": "object", "additionalProperties": false, "properties": { "basis": { "const": "stored_billing_items" }, "invalid_item_count": { "type": "string", "pattern": "^[0-9]+$" }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "usage": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$" } }, "required": [ "name", "usage" ] } } }, "required": [ "basis", "invalid_item_count", "items" ] }, "UsageSummaryTotals": { "type": "object", "additionalProperties": false, "properties": { "request_count": { "type": "string", "pattern": "^[0-9]+$" }, "pending_request_count": { "type": "string", "pattern": "^[0-9]+$" }, "credits": { "type": "object", "additionalProperties": false, "properties": { "before_discount": { "$ref": "#/components/schemas/CreditAmount" }, "after_discount": { "$ref": "#/components/schemas/CreditAmount" } }, "required": [ "before_discount", "after_discount" ] }, "tokens": { "$ref": "#/components/schemas/UsageSummaryTokens" }, "billing_dimensions": { "$ref": "#/components/schemas/UsageSummaryDimensions" } }, "required": [ "request_count", "pending_request_count", "credits", "tokens" ] }, "UsageSummaryGroup": { "type": "object", "additionalProperties": false, "properties": { "key": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": [ "string", "null" ] } }, "required": [ "id", "label" ] }, { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, { "type": "object", "additionalProperties": false, "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "kind": { "enum": [ "model", "metered" ] } }, "required": [ "id", "name", "kind" ] }, { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, { "type": "object", "additionalProperties": false, "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" } }, "required": [ "start", "end" ] } ] }, "totals": { "$ref": "#/components/schemas/UsageSummaryTotals" } }, "required": [ "key", "totals" ] }, "UsageSummary": { "type": "object", "additionalProperties": false, "properties": { "schema_version": { "const": 2 }, "window": { "type": "object", "additionalProperties": false, "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" }, "end_exclusive": { "const": true }, "timezone": { "type": "string" } }, "required": [ "start", "end", "end_exclusive", "timezone" ] }, "scope": { "type": "object", "additionalProperties": false, "properties": { "organization_id": { "type": "string", "format": "uuid" }, "team_id": { "type": [ "string", "null" ], "format": "uuid" }, "api_key_id": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "organization_id", "team_id", "api_key_id" ] }, "data": { "type": "object", "additionalProperties": false, "properties": { "basis": { "const": "persisted_request_logs" }, "snapshot_observed_at": { "type": "string", "format": "date-time" }, "aggregation_version": { "const": 1 }, "source": { "const": "raw" } }, "required": [ "basis", "snapshot_observed_at", "aggregation_version", "source" ] }, "totals": { "$ref": "#/components/schemas/UsageSummaryTotals" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/UsageSummaryGroup" } }, "total": { "type": "integer", "minimum": 0, "maximum": 100000 }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "per_page": { "type": "integer", "minimum": 1, "maximum": 200 } }, "required": [ "schema_version", "window", "scope", "data", "totals" ] }, "CreateOrganizationManagementTokenRequest": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "去除首尾空白后为 1–120 个 UTF-8 字节。" }, "scopes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "usage:read", "usage:aggregate", "pricing:read" ] }, "description": "完整 scope 集合，不与原集合合并。各 scope 独立，至少一项。" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "省略或 null 表示无到期时间；指定时间必须晚于当前时刻。" } }, "required": [ "name", "scopes" ] }, "UpdateOrganizationManagementTokenRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "去除首尾空白后为 1–120 个 UTF-8 字节。" }, "scopes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "usage:read", "usage:aggregate", "pricing:read" ] }, "description": "完整 scope 集合，不与原集合合并。各 scope 独立，至少一项。" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "省略表示不变，null 清除到期时间；指定时间必须晚于当前时刻。" } } }, "ErrorResponse": { "type": "object", "additionalProperties": false, "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "Decimal": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$", "description": "十进制定点字符串，禁止用浮点数重算财务结果。" }, "ManagementTokenScope": { "type": "string", "enum": [ "api_keys:read", "api_keys:write", "usage:read", "pricing:read", "usage:aggregate" ] }, "CreateManagementTokenRequest": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "去除首尾空白后为 1–120 个 UTF-8 字节。" }, "scopes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/ManagementTokenScope" }, "description": "完整 scope 集合，不与原集合合并。各 scope 独立，至少一项。" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "省略或 null 表示无到期时间；指定时间必须晚于当前时刻。" } }, "required": [ "name", "scopes" ] }, "UpdateManagementTokenRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "去除首尾空白后为 1–120 个 UTF-8 字节。" }, "scopes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/ManagementTokenScope" }, "description": "完整 scope 集合，不与原集合合并。各 scope 独立，至少一项。" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "省略表示不变，null 清除到期时间；指定时间必须晚于当前时刻。" } } }, "ManagementToken": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "key_prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/ManagementTokenScope" } }, "created_by": { "type": "string", "format": "uuid" }, "created_by_name": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time", "description": "近似最近通过认证的时间，最多每五分钟更新一次。null 不证明从未尝试调用，非 null 不证明业务操作成功。" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "active", "expired", "revoked" ] }, "scope_type": { "type": "integer", "enum": [ 0, 1 ], "description": "0 为组织 Token，1 为团队 Token。" }, "organization_id": { "type": "string", "format": "uuid", "description": "Token 固定所属组织，不继承创建者的平台角色。" }, "team_id": { "type": [ "string", "null" ], "format": "uuid", "description": "团队 Token 固定所属团队；组织 Token 为 null。" } }, "required": [ "id", "name", "key_prefix", "scopes", "created_by", "created_by_name", "expires_at", "revoked_at", "last_used_at", "created_at", "updated_at", "status", "scope_type", "organization_id", "team_id" ] }, "ManagementTokenCreated": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "key_prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/ManagementTokenScope" } }, "created_by": { "type": "string", "format": "uuid" }, "created_by_name": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time", "description": "近似最近通过认证的时间，最多每五分钟更新一次。null 不证明从未尝试调用，非 null 不证明业务操作成功。" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "active", "expired", "revoked" ] }, "secret": { "type": "string", "description": "仅本次响应返回。" }, "scope_type": { "type": "integer", "enum": [ 0, 1 ], "description": "0 为组织 Token，1 为团队 Token。" }, "organization_id": { "type": "string", "format": "uuid", "description": "Token 固定所属组织，不继承创建者的平台角色。" }, "team_id": { "type": [ "string", "null" ], "format": "uuid", "description": "团队 Token 固定所属团队；组织 Token 为 null。" } }, "required": [ "id", "name", "key_prefix", "scopes", "created_by", "created_by_name", "expires_at", "revoked_at", "last_used_at", "created_at", "updated_at", "status", "secret", "scope_type", "organization_id", "team_id" ] }, "CreateManagedApiKeyRequest": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": [ "string", "null" ] }, "overdraft_enabled": { "type": [ "boolean", "null" ], "description": "省略或 null 时继承组织与团队的有效预支开关。显式 false 关闭预支。" }, "overdraft_limit": { "anyOf": [ { "$ref": "#/components/schemas/CreditAmount" }, { "type": "null" } ], "description": "非负 Credits。启用预支时，省略或 null 默认为无限 Key 级上限，仍受父级限制；关闭预支时上限为零。 必须是 0.000005 ℂ 的整数倍，最大 49999999999999.999995 ℂ。超出范围或精度要求的输入返回 400，不自动舍入。" } } }, "UpdateManagedApiKeyRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "label": { "type": [ "string", "null" ], "description": "省略或 null 表示不变；空字符串清除标签。" }, "overdraft_enabled": { "type": [ "boolean", "null" ], "description": "省略或 null 表示不变。false 同时把 Key 级上限设为零，不清除欠款。" }, "overdraft_limit": { "anyOf": [ { "$ref": "#/components/schemas/CreditAmount" }, { "type": "null" } ], "description": "非负 Credits。省略或 null 保留上限；关闭预支时上限为零。启用或提高额度仍受父级设置限制。 必须是 0.000005 ℂ 的整数倍，最大 49999999999999.999995 ℂ。超出范围或精度要求的输入返回 400，不自动舍入。" } } }, "ManagedApiKeyCreated": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "key_prefix": { "type": "string" } }, "required": [ "id", "key", "key_prefix" ] }, "ApiKeyBudgetSummary": { "type": "object", "additionalProperties": false, "properties": { "budget_type": { "type": "string", "enum": [ "all_time", "windowed" ] }, "amount": { "$ref": "#/components/schemas/CreditAmount" }, "window_days": { "type": [ "integer", "null" ], "minimum": 1 }, "is_enabled": { "type": "boolean" }, "is_blocked": { "type": "boolean" } }, "required": [ "budget_type", "amount", "window_days", "is_enabled", "is_blocked" ] }, "ManagedApiKey": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "team_id": { "type": "string", "format": "uuid" }, "owner_id": { "type": [ "string", "null" ], "format": "uuid", "description": "人员创建的 Key 可有 owner；管理 Token 创建的 Key 为 null。" }, "owner_email": { "type": [ "string", "null" ], "format": "email", "description": "存量团队管理响应中的 owner 邮箱，无法解析时为 null。" }, "key_prefix": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "balance": { "$ref": "#/components/schemas/CreditAmount", "description": "已对账的 Key 净余额，可为负。已包含在 available_credits 中，不要重复相加。" }, "available_credits": { "$ref": "#/components/schemas/CreditAmount", "description": "有效可访问订单余额加 Key 净余额，不包含未来预支。共享额度不为本 Key 预留。" }, "consumed_credits": { "$ref": "#/components/schemas/CreditAmount", "description": "历史已记录的折后 Credits，不是当前周期预算支出；近期用量可能延迟出现。" }, "original_consumed_credits": { "$ref": "#/components/schemas/CreditAmount", "description": "同一历史范围的折前 Credits。" }, "discount_savings_credits": { "$ref": "#/components/schemas/CreditAmount", "description": "折前减折后，最低为零。" }, "overdraft_enabled": { "type": "boolean" }, "overdraft_limit": { "$ref": "#/components/schemas/CreditAmount" }, "effective_overdraft_enabled": { "type": "boolean", "description": "当前 Key、团队与组织开关均生效，不保证父级共享额度可用或模型请求获准。" }, "can_configure_overdraft": { "type": "boolean", "description": "父级设置是否允许配置预支，不是模型调用许可。" }, "overdraft_unavailable_reason": { "type": [ "string", "null" ], "enum": [ "organization_disabled", "team_disabled", null ] }, "budgets": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyBudgetSummary" }, "description": "最多两项配置摘要，不包含消费与重置时间。使用 budgets 或 quota 接口读取详情。" } }, "required": [ "id", "team_id", "owner_id", "owner_email", "key_prefix", "label", "balance", "available_credits", "consumed_credits", "original_consumed_credits", "discount_savings_credits", "overdraft_enabled", "overdraft_limit", "effective_overdraft_enabled", "can_configure_overdraft", "overdraft_unavailable_reason", "budgets" ] }, "RevealApiKeyResponse": { "type": "object", "additionalProperties": false, "properties": { "key": { "type": [ "string", "null" ] } }, "required": [ "key" ] }, "UpsertApiKeyBudgetRequest": { "type": "object", "additionalProperties": false, "properties": { "amount": { "$ref": "#/components/schemas/CreditAmount", "description": "每次 PUT 必填，严格大于零，单位为 Credits。不是充值。 必须是 0.000005 ℂ 的整数倍，最大 49999999999999.999995 ℂ。超出范围或精度要求的输入返回 400，不自动舍入。" }, "window_days": { "type": [ "integer", "null" ], "minimum": 1, "description": "windowed 每次 PUT 必填且至少为 1；all_time 省略或 null。一天为固定 86400 秒，超出支持的日期范围返回 400。" }, "starts_at": { "type": [ "string", "null" ], "format": "date-time", "description": "首次设置时省略或 null 默认为当前时刻；更新时保留原值。显式更改会改变总额预算的统计起点或周期预算的锚点。" }, "is_enabled": { "type": [ "boolean", "null" ], "description": "首次设置时省略或 null 默认为 true；更新时保留原值。false 停用限制但保留配置。" } }, "required": [ "amount" ] }, "ApiKeyBudget": { "type": "object", "additionalProperties": false, "properties": { "budget_type": { "type": "string", "enum": [ "all_time", "windowed" ] }, "amount": { "$ref": "#/components/schemas/CreditAmount" }, "window_days": { "type": [ "integer", "null" ], "minimum": 1 }, "starts_at": { "type": "string", "format": "date-time" }, "is_enabled": { "type": "boolean" }, "current_consumed": { "$ref": "#/components/schemas/CreditAmount", "description": "当前已记录的预算支出，可能延迟。all_time 从 starts_at 起算；windowed 仅当前固定周期。未到 starts_at 时为零。" }, "remaining": { "$ref": "#/components/schemas/CreditAmount", "description": "始终为 max(amount-current_consumed,0)，停用或未开始时也返回数值。不是可消费额度；与 quota 中可能为 null 的 remaining_credits 口径不同。" }, "segment_start": { "type": [ "string", "null" ], "format": "date-time" }, "segment_end": { "type": [ "string", "null" ], "format": "date-time", "description": "仅已开始的 windowed 预算有值；停用时仍可返回周期边界，不表示会执行重置。all_time 为 null。" }, "is_blocked": { "type": "boolean", "description": "预算拦截状态可能延迟更新。不是消费是否超限或模型是否可调用的同步判定。" } }, "required": [ "budget_type", "amount", "window_days", "starts_at", "is_enabled", "current_consumed", "remaining", "segment_start", "segment_end", "is_blocked" ] }, "UsageDimension": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "usage": { "type": "integer", "minimum": 0, "description": "非负 JSON 整数，与区间汇总的整数字符串不同。超出客户端安全整数范围时使用无损 JSON 数值解析。" } }, "required": [ "name", "usage" ] }, "CreditSummary": { "type": "object", "additionalProperties": false, "properties": { "before_discount": { "$ref": "#/components/schemas/CreditAmount" }, "after_discount": { "$ref": "#/components/schemas/CreditAmount" } }, "required": [ "before_discount", "after_discount" ] }, "UsageResponse": { "type": "object", "additionalProperties": false, "properties": { "usage_id": { "type": "string", "format": "uuid", "description": "来自模型响应头 x-cr-usage-id 的稳定账单 UUID；轮询和幂等重试保持相同。" }, "billing_status": { "type": "string", "enum": [ "pending", "final" ], "description": "pending 表示费用未落定，不表示免费；final 不表示生成成功。" }, "created_at": { "type": "string", "format": "date-time" }, "usage_items": { "type": "array", "items": { "$ref": "#/components/schemas/UsageDimension" }, "description": "按维度名称排序。pending 为空数组；final 的空数组也不能证明模型没有产生用量。" }, "credits": { "anyOf": [ { "$ref": "#/components/schemas/CreditSummary" }, { "type": "null" } ], "description": "pending 为 null。已落定金额是历史账单值，不能用当前模型价格重算。" } }, "required": [ "usage_id", "billing_status", "created_at", "usage_items", "credits" ] }, "BatchUsageRequest": { "type": "object", "additionalProperties": false, "properties": { "usage_ids": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string", "format": "uuid" } } }, "required": [ "usage_ids" ] }, "BatchUsageItem": { "type": "object", "additionalProperties": false, "properties": { "usage_id": { "type": "string" }, "lookup_status": { "type": "string", "enum": [ "found", "not_found" ], "description": "found 仍可能为 pending；not_found 合并不存在、暂不可查与无权访问，此时 usage=null。" }, "usage": { "anyOf": [ { "$ref": "#/components/schemas/UsageResponse" }, { "type": "null" } ] } }, "required": [ "usage_id", "lookup_status", "usage" ] }, "BatchUsageResponse": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BatchUsageItem" } } }, "required": [ "items" ] }, "PriceTier": { "type": "object", "additionalProperties": false, "properties": { "up_to": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "const": "unbounded" } ] }, "unit_price": { "$ref": "#/components/schemas/CreditUnitPrice" } }, "required": [ "up_to", "unit_price" ] }, "DimensionPrice": { "oneOf": [ { "$ref": "#/components/schemas/CreditUnitPrice" }, { "type": "object", "additionalProperties": false, "properties": { "tiers": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/PriceTier" } } }, "required": [ "tiers" ] }, { "type": "object", "additionalProperties": false, "properties": { "request_input_tiers": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/PriceTier" } } }, "required": [ "request_input_tiers" ] }, { "type": "object", "additionalProperties": false, "properties": { "video_tiers": { "type": "array", "minItems": 1, "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "properties": { "resolution": { "type": "string", "enum": [ "480P", "720P", "1080P", "2K", "4K" ] }, "reference_video": { "type": "boolean" }, "unit_price": { "$ref": "#/components/schemas/CreditUnitPrice" } }, "required": [ "resolution", "reference_video", "unit_price" ] }, "description": "根据输出分辨率及是否输入参考视频选择对应单价。" } }, "required": [ "video_tiers" ] } ] }, "PricingMap": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/DimensionPrice" }, "description": "各计费维度的单价，单位为 Credits（ℂ）/单个计费单位。每百万 token 的 Credits 单价等于接口单价乘以 1,000,000。" }, "PublicModelMetadata": { "type": "object", "additionalProperties": false, "properties": { "display_name": { "type": "string" }, "brand": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "status": { "type": "string" }, "price_caption": { "type": "string" }, "context_window": { "type": "integer", "minimum": 1 }, "max_output_tokens": { "type": "integer", "minimum": 1 }, "tags": { "type": "array", "items": { "type": "string" } } } }, "EffectiveModelPricing": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/PublicModelMetadata" }, "effective_pricing": { "$ref": "#/components/schemas/PricingMap", "description": "当前折后价格，单位为 Credits/计费单位。保留固定价与阶梯结构；不代表历史账单单价。" }, "pricing": { "$ref": "#/components/schemas/PricingMap", "description": "规范化后的公开标价；数值为十进制定点字符串。" }, "discount": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "万分比收费乘数，7500 表示收取标价的 75%；无有效折扣时为 10000。" } }, "required": [ "name", "metadata", "pricing", "discount", "effective_pricing" ] }, "CreditAmount": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]{1,6})?$", "x-crr-unit": "credits", "description": "金额，单位为 Credits（ℂ），与控制台一致。精确十进制字符串，最多六位小数，不固定补零。例如 \"0.00553\" 表示 0.00553 ℂ。" }, "CreditUnitPrice": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$", "x-crr-unit": "credits_per_usage_unit", "description": "单价，单位为 Credits（ℂ）/单个计费单位，保留完整十进制精度。每百万 token 的 Credits 单价等于接口单价乘以 1,000,000。" } }, "responses": { "BadRequest": { "description": "请求无效。业务字段或组合校验失败返回 application/json；JSON 语法或 UUID 路径解析失败返回 text/plain。按 Content-Type 解析，纯文本措辞不保证稳定。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "type": "string" } } } }, "InvalidUserJwt": { "description": "登录 JWT 缺失、无效、过期，或当前用户会话已失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InvalidManagementToken": { "description": "管理 Token 缺失、无效、过期、撤销，或绑定的组织或团队已移除。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Forbidden": { "description": "角色或团队作用域不足。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InsufficientScope": { "description": "Token 缺少此接口要求的 scope。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "资源不存在。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ScopedNotFound": { "description": "资源不存在或不属于 Token 的团队；两者统一返回 404。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RateLimited": { "description": "超过管理查询限流。批量按输入 ID 数消耗单位，不是额外 Credits 扣费。旧接口可能不返回 Retry-After；客户端仍须有限退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InternalError": { "description": "服务暂时不可用。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InvalidPath": { "description": "UUID 路径参数无效。返回纯文本，不是 JSON 错误对象；措辞不保证稳定。", "content": { "text/plain": { "schema": { "type": "string" } } } }, "RequestBodyTooLarge": { "description": "JSON 请求体超过服务允许的大小。返回纯文本，不应原样重试。服务默认上限为 2 MiB；部署入口可能设置更低限制。", "content": { "text/plain": { "schema": { "type": "string" } } } }, "UnsupportedMediaType": { "description": "缺少 Content-Type 或媒体类型不是 JSON。使用 application/json。返回纯文本，措辞不保证稳定。", "content": { "text/plain": { "schema": { "type": "string" } } } }, "InvalidJsonData": { "description": "JSON 语法有效，但字段类型不匹配或缺少必填字段；批量查账也拒绝未知字段。返回纯文本，不是额度或汇总接口的查询规模错误；修正请求后再发送。", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "headers": { "CreditUnit": { "description": "响应中金额字段的单位：Credits（ℂ）。", "schema": { "type": "string", "const": "credits" } } } }, "x-crr-credit-unit": "credits" }