{ "swagger": "2.0", "info": { "description": "以个人 Access Token（Bearer mgpat_...）调用的公开 API：账户余额、用量、费用、单次调用与 API Key 管理。\\n\\n鉴权：`Authorization: Bearer \u003ctoken\u003e`。\\n错误：使用真实 HTTP 状态码，响应体为 `{\"error\":{\"code\",\"error_class\",\"reason\",\"message\",\"request_id\",\"trace_id\"}}`，响应头带 X-Request-ID。请按 `code` 与 `reason` 处理，`message` 仅供排查。\\n金额：站点结算币种的十进制字符串（CNY/USD），不做汇率换算。\\n时间：UTC RFC3339。\\n\\n错误码：\\n\\n| HTTP | code | reason | 含义 |\\n|---|---|---|---|\\n| 400 | invalid_request | 出错的参数名（如 window、limit、cursor、Idempotency-Key），也可能是 body 或 _root（跨字段校验） | 参数缺失或不合法；无法定位到单个字段时不返回 reason |\\n| 401 | invalid_token | malformed / not_found / revoked / expired / invalid_snapshot | 未带 Bearer Token 或格式、校验尾不对 / Token 不存在 / 已撤销（含被重新生成替换） / 已过期 / 服务端身份快照不完整（重试，或重新生成 Token） |\\n| 401 | unauthorized | not_visible | 单次调用不存在或不在你的可见范围（两者不区分） |\\n| 403 | account_inactive | account_inactive | 账号已停用 |\\n| 403 | forbidden | access_denied / tenant_required / 空 | 不是 X-Tenant-Id 所指租户的成员（租户被冻结/停用时同样返回本码，不单独披露状态） / 未确定租户（未传 X-Tenant-Id 且账号未设置默认租户） / 角色无权查看该范围 |\\n| 404 | not_found | 空 / expired | 资源或路径不存在 / 导出文件已过期 |\\n| 409 | conflict | not_ready / failed / 空 | 导出尚未完成 / 导出失败 / 资源状态冲突 |\\n| 409 | idempotency_conflict | key_reuse / in_progress | 同一个 Idempotency-Key 用于不同请求 / 上一次请求仍在处理，按 Retry-After 重试 |\\n| 413 | invalid_request | body | 请求体超过 1 MiB |\\n| 429 | rate_limited | 空 | 超出限流，带 Retry-After；X-RateLimit-Limit / Remaining / Reset 只在平台自身限流时出现，上游供应商限流只保证 Retry-After |\\n| 500 | internal_error | 空 | 服务内部错误 |\\n| 502 | upstream_error | 空 | 轮换未返回新 Key，旧 Key 仍有效 |\\n| 503 | idempotency_unavailable | 空 | 幂等存储不可用，写操作暂停，请稍后重试 |", "title": "ModelGo Public API", "contact": {}, "version": "1.0.0" }, "basePath": "/api/openapi/v1", "paths": { "/cost": { "get": { "security": [ { "BearerPAT": [] } ], "description": "客户实际扣费与三组件拆分；total_amount 为权威值，差额进 other_amount。\nstatus=estimated|settled|pending|reversed 时改从 billing 账本读取该状态的金额（estimated=预授权报价、settled=已结算 actual_amount、pending=在途预授权、reversed=已冲正），此时不返回组件拆分。\n传 X-Tenant-Id：返回该租户的单个 CostResponse。\n不传 X-Tenant-Id：返回该账号全部有权限（active 成员）租户的列表 {\"items\":[CostResponse,...]}，按 tenant_id 排序；无权租户不出现；单个租户读取失败时该项 error=unavailable，不影响其他租户。", "produces": [ "application/json" ], "tags": [ "public" ], "summary": "费用查询", "parameters": [ { "type": "string", "description": "目标租户；缺省返回所有有权限租户的列表", "name": "X-Tenant-Id", "in": "header" }, { "type": "string", "description": "RFC3339 或 YYYY-MM-DD", "name": "from", "in": "query" }, { "type": "string", "description": "RFC3339 或 YYYY-MM-DD", "name": "to", "in": "query" }, { "type": "string", "description": "模型键", "name": "model", "in": "query" }, { "type": "string", "description": "API Key ID", "name": "api_key_id", "in": "query" }, { "type": "string", "description": "工作空间 ID", "name": "workspace_id", "in": "query" }, { "enum": [ "estimated", "settled", "pending", "reversed" ], "type": "string", "description": "estimated|settled|pending|reversed 时按 billing 账本状态聚合", "name": "status", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/openapi.CostResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } } } } }, "/generations/by-billing-session/{session_id}": { "get": { "security": [ { "BearerPAT": [] } ], "description": "用 generation_id（billing_session_id）查询同一次调用；不存在或不可见统一 401。", "produces": [ "application/json" ], "tags": [ "public" ], "summary": "单次调用详情（按 billing session id）", "parameters": [ { "type": "string", "description": "目标租户", "name": "X-Tenant-Id", "in": "header" }, { "type": "string", "description": "billing_session_id", "name": "session_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/openapi.GenerationDetail" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } } } } }, "/generations/{id}": { "get": { "security": [ { "BearerPAT": [] } ], "description": "按 request_id 查询状态、用量、延迟与费用；不可见/不存在统一 401。", "produces": [ "application/json" ], "tags": [ "public" ], "summary": "单次调用详情", "parameters": [ { "type": "string", "description": "目标租户", "name": "X-Tenant-Id", "in": "header" }, { "type": "string", "description": "request_id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/openapi.GenerationDetail" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } } } } }, "/generations/{id}/content": { "get": { "security": [ { "BearerPAT": [] } ], "description": "调用时未开启采集时返回 available=false；kind 必填。", "produces": [ "application/json" ], "tags": [ "public" ], "summary": "单次调用原文", "parameters": [ { "type": "string", "description": "目标租户", "name": "X-Tenant-Id", "in": "header" }, { "type": "string", "description": "request_id", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "request|response", "name": "kind", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/openapi.GenerationContent" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } } } } }, "/management/exports": { "get": { "security": [ { "BearerPAT": [] } ], "description": "返回当前账号创建的导出任务，最新在前。", "produces": [ "application/json" ], "tags": [ "public" ], "summary": "导出任务列表", "parameters": [ { "type": "integer", "description": "1-100，默认 50", "name": "limit", "in": "query" }, { "type": "string", "description": "不透明游标", "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/openapi.ExportListResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } } } }, "post": { "security": [ { "BearerPAT": [] } ], "description": "异步导出 usage / cost / generations；写操作需 Idempotency-Key。产物 24 小时后过期。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "public" ], "summary": "创建导出任务", "parameters": [ { "type": "string", "description": "目标租户", "name": "X-Tenant-Id", "in": "header" }, { "description": "导出参数", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/openapi.ExportCreateRequest" } } ], "responses": { "202": { "description": "Accepted", "schema": { "$ref": "#/definitions/openapi.ExportJobView" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } } } } }, "/management/exports/{export_id}": { "get": { "security": [ { "BearerPAT": [] } ], "produces": [ "application/json" ], "tags": [ "public" ], "summary": "导出任务详情", "parameters": [ { "type": "string", "description": "导出任务 ID", "name": "export_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/openapi.ExportJobView" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } } } } }, "/management/exports/{export_id}/download": { "get": { "security": [ { "BearerPAT": [] } ], "description": "CSV/JSON 附件；任务未完成返回 409，过期或不存在统一 404。", "produces": [ "text/csv", "application/json" ], "tags": [ "public" ], "summary": "下载导出产物", "parameters": [ { "type": "string", "description": "导出任务 ID", "name": "export_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "file" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } } } } }, "/management/keys": { "get": { "security": [ { "BearerPAT": [] } ], "description": "按 workspace 作用域分页；status 支持 active|disabled|revoked|expired|expiring。", "produces": [ "application/json" ], "tags": [ "management" ], "summary": "列出 API Key", "parameters": [ { "type": "string", "description": "目标租户", "name": "X-Tenant-Id", "in": "header" }, { "type": "string", "description": "工作空间 ID", "name": "workspace_id", "in": "query", "required": true }, { "type": "string", "description": "不透明游标", "name": "cursor", "in": "query" }, { "type": "integer", "description": "1-200，默认 50", "name": "limit", "in": "query" }, { "type": "string", "description": "名称关键字", "name": "q", "in": "query" }, { "type": "string", "description": "personal|member|service", "name": "key_type", "in": "query" }, { "type": "string", "description": "active|disabled|revoked|expired|expiring", "name": "status", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/openapi.ManagedKeyList" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } } } }, "post": { "security": [ { "BearerPAT": [] } ], "description": "仅支持 personal Key；写操作必须携带 Idempotency-Key，重试会回放同一响应。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "management" ], "summary": "创建 API Key（明文仅一次）", "parameters": [ { "type": "string", "description": "目标租户", "name": "X-Tenant-Id", "in": "header" }, { "type": "string", "description": "幂等键（≤128）", "name": "Idempotency-Key", "in": "header", "required": true }, { "description": "workspace_id/name/expires_at/spending_limit", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/openapi.ManagedKeyCreateRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/openapi.ManagedKeyCreateResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } } } } }, "/management/keys/{key_id}": { "get": { "security": [ { "BearerPAT": [] } ], "produces": [ "application/json" ], "tags": [ "management" ], "summary": "API Key 详情", "parameters": [ { "type": "string", "description": "目标租户", "name": "X-Tenant-Id", "in": "header" }, { "type": "string", "description": "工作空间 ID", "name": "workspace_id", "in": "query", "required": true }, { "type": "string", "description": "API Key ID", "name": "key_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/openapi.ManagedKey" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } } } }, "delete": { "security": [ { "BearerPAT": [] } ], "description": "立即失效；保留 status=revoked 供审计。", "tags": [ "management" ], "summary": "撤销 API Key", "parameters": [ { "type": "string", "description": "目标租户", "name": "X-Tenant-Id", "in": "header" }, { "type": "string", "description": "幂等键", "name": "Idempotency-Key", "in": "header", "required": true }, { "type": "string", "description": "工作空间 ID", "name": "workspace_id", "in": "query", "required": true }, { "type": "string", "description": "API Key ID", "name": "key_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } } } }, "patch": { "security": [ { "BearerPAT": [] } ], "description": "name/expires_at/spending_limit 三态：缺省不变、null 清除、传值设置；未知字段 400。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "management" ], "summary": "更新 API Key（名称/过期/预算）", "parameters": [ { "type": "string", "description": "目标租户", "name": "X-Tenant-Id", "in": "header" }, { "type": "string", "description": "幂等键", "name": "Idempotency-Key", "in": "header", "required": true }, { "type": "string", "description": "工作空间 ID", "name": "workspace_id", "in": "query", "required": true }, { "type": "string", "description": "API Key ID", "name": "key_id", "in": "path", "required": true }, { "description": "name/expires_at/spending_limit", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/openapi.ManagedKeyUpdateRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/openapi.ManagedKey" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } } } } }, "/management/keys/{key_id}/disable": { "post": { "security": [ { "BearerPAT": [] } ], "tags": [ "management" ], "summary": "停用 API Key", "parameters": [ { "type": "string", "description": "目标租户", "name": "X-Tenant-Id", "in": "header" }, { "type": "string", "description": "幂等键", "name": "Idempotency-Key", "in": "header", "required": true }, { "type": "string", "description": "工作空间 ID", "name": "workspace_id", "in": "query", "required": true }, { "type": "string", "description": "API Key ID", "name": "key_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } } } } }, "/management/keys/{key_id}/enable": { "post": { "security": [ { "BearerPAT": [] } ], "tags": [ "management" ], "summary": "启用 API Key", "parameters": [ { "type": "string", "description": "目标租户", "name": "X-Tenant-Id", "in": "header" }, { "type": "string", "description": "幂等键", "name": "Idempotency-Key", "in": "header", "required": true }, { "type": "string", "description": "工作空间 ID", "name": "workspace_id", "in": "query", "required": true }, { "type": "string", "description": "API Key ID", "name": "key_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } } } } }, "/management/keys/{key_id}/rotate": { "post": { "security": [ { "BearerPAT": [] } ], "description": "返回新明文一次并立即确认轮换；若确认失败仍返回新 Key 且 previous_key_active=true。", "produces": [ "application/json" ], "tags": [ "management" ], "summary": "轮换 API Key（单步）", "parameters": [ { "type": "string", "description": "目标租户", "name": "X-Tenant-Id", "in": "header" }, { "type": "string", "description": "幂等键", "name": "Idempotency-Key", "in": "header", "required": true }, { "type": "string", "description": "工作空间 ID", "name": "workspace_id", "in": "query", "required": true }, { "type": "string", "description": "API Key ID", "name": "key_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/openapi.ManagedKeyRotation" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } }, "502": { "description": "Bad Gateway", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } } } } }, "/management/keys/{key_id}/rotate/confirm": { "post": { "security": [ { "BearerPAT": [] } ], "tags": [ "management" ], "summary": "确认轮换（补偿接口）", "parameters": [ { "type": "string", "description": "目标租户", "name": "X-Tenant-Id", "in": "header" }, { "type": "string", "description": "幂等键", "name": "Idempotency-Key", "in": "header", "required": true }, { "type": "string", "description": "工作空间 ID", "name": "workspace_id", "in": "query", "required": true }, { "type": "string", "description": "API Key ID", "name": "key_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } } } } }, "/requests/{id}": { "get": { "security": [ { "BearerPAT": [] } ], "description": "与 /generations/{id} 指向同一 lookup。", "produces": [ "application/json" ], "tags": [ "public" ], "summary": "单次调用详情（兼容别名）", "parameters": [ { "type": "string", "description": "目标租户", "name": "X-Tenant-Id", "in": "header" }, { "type": "string", "description": "request_id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/openapi.GenerationDetail" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } } } } }, "/usage": { "get": { "security": [ { "BearerPAT": [] } ], "description": "按窗口返回 summary 与分桶 series。granularity=hour|day|month；group_by=none|model|workspace|member|api_key；窗口有上限；timezone 仅 UTC。窗口内无数据（含未知/下架模型）时，group_by=none 返回完整零值桶（含空桶），不是空数组。\n传 X-Tenant-Id：返回该租户的单个 UsageResponse。\n不传 X-Tenant-Id：返回该账号全部有权限（active 成员）租户的列表 {\"items\":[UsageResponse,...]}，按 tenant_id 排序；无权租户不出现；单个租户读取失败时该项 error=unavailable，不影响其他租户。", "produces": [ "application/json" ], "tags": [ "public" ], "summary": "用量查询", "parameters": [ { "type": "string", "description": "目标租户；缺省返回所有有权限租户的列表", "name": "X-Tenant-Id", "in": "header" }, { "type": "string", "description": "RFC3339 或 YYYY-MM-DD", "name": "from", "in": "query" }, { "type": "string", "description": "RFC3339 或 YYYY-MM-DD", "name": "to", "in": "query" }, { "enum": [ "hour", "day", "month" ], "type": "string", "description": "hour|day|month", "name": "granularity", "in": "query" }, { "enum": [ "none", "model", "workspace", "member", "api_key" ], "type": "string", "description": "none|model|workspace|member|api_key", "name": "group_by", "in": "query" }, { "type": "string", "description": "模型键", "name": "model", "in": "query" }, { "type": "string", "description": "API Key ID", "name": "api_key_id", "in": "query" }, { "type": "string", "description": "工作空间 ID", "name": "workspace_id", "in": "query" }, { "type": "string", "description": "仅支持 UTC", "name": "timezone", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/openapi.UsageResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } } } } }, "/user/balance": { "get": { "security": [ { "BearerPAT": [] } ], "description": "Bearer PAT 鉴权。金额为站点结算币种十进制字符串。\n传 X-Tenant-Id：返回该租户的单个余额对象（BalanceResponse）。\n不传 X-Tenant-Id：返回该账号全部有权限（active 成员）租户的余额列表 {\"items\":[BalanceResponse,...]}，按 tenant_id 排序；无权访问的租户不出现；某个租户读取失败时该项 balance_status=unavailable 且不填金额。", "produces": [ "application/json" ], "tags": [ "public" ], "summary": "账户余额", "parameters": [ { "type": "string", "description": "目标租户；缺省返回所有有权限租户的余额列表", "name": "X-Tenant-Id", "in": "header" } ], "responses": { "200": { "description": "传 X-Tenant-Id 时为单对象；缺省时为 BalanceListResponse", "schema": { "$ref": "#/definitions/openapi.BalanceResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/openapi.OpenAPIError" } } } } } }, "definitions": { "apikey.Limit": { "type": "object", "properties": { "amount": { "type": "string" }, "currency": { "type": "string" }, "period": { "description": "Period is the PRD (#381) reset vocabulary: none|daily|monthly. Canonical\nfor the console; period_unit/period_length are the derived legacy shape.\n'total' is unsupported (lifetime cumulative → full-history scan).", "type": "string", "enum": [ "none", "daily", "monthly" ], "example": "monthly" }, "period_length": { "type": "integer", "example": 1 }, "period_unit": { "type": "string", "enum": [ "hour", "day", "week", "month", "none" ], "example": "month" } } }, "openapi.BalanceResponse": { "type": "object", "properties": { "available": { "type": "string" }, "balance": { "description": "Balance and Available are the truly spendable amount: cash + grant +\nrebate. Each bucket already nets out its frozen_balance, so reserved must\nnot be subtracted again. Both fields carry the same value (kept for client\ncompatibility); read this instead of deriving total - used.", "type": "string" }, "balance_status": { "description": "unavailable means the tenant is a valid membership but its upstream read\nfailed; amounts are omitted rather than fabricated as zero.", "type": "string", "enum": [ "ok", "partial", "arrears", "insufficient", "unavailable" ] }, "currency": { "type": "string" }, "gift": { "type": "string" }, "is_active": { "type": "boolean" }, "is_personal": { "description": "IsPersonal marks the account's own personal tenant (one owner) rather\nthan an enterprise tenant, so clients can render personal/org balances\ndifferently without a second tenant lookup.", "type": "boolean" }, "main": { "type": "string" }, "reserved": { "type": "string" }, "reward": { "type": "string" }, "tenant_id": { "type": "string" }, "total": { "description": "Total/Used are owner/admin-only, matching the console's tenant-level spend\nvisibility, and are omitted when their upstream read fails (the request\nthen reports balance_status=partial rather than fabricating zeros).\nTotal = used + available + reserved (traceable credit volume; it is not\nthe spendable amount). Used is all-time settled consumption.", "type": "string" }, "updated_at": { "description": "UpdatedAt is billing's cash-ledger balance row's last change. It is NOT\nthe request time, and grant/rebate movements (spend draws those first) do\nnot move it.", "type": "string" }, "used": { "type": "string" } } }, "openapi.CostResponse": { "type": "object", "properties": { "billing_as_of": { "description": "BillingAsOf is the settlement ledger's closed-through watermark.", "type": "string" }, "cache_amount": { "type": "string" }, "currency": { "type": "string" }, "data_as_of": { "description": "DataAsOf is the log pipeline's newest event time (global).", "type": "string" }, "discount_amount": { "type": "string", "x-nullable": true }, "error": { "description": "Error is set only for a failed tenant in the list form; single-tenant\nreads report failures as a normal OpenAPI error response instead.", "type": "string" }, "input_amount": { "type": "string" }, "is_final": { "description": "IsFinal is true when the window ended at least the grace period before\nboth watermarks.", "type": "boolean" }, "media_amount": { "description": "MediaAmount / RequestAmount / DiscountAmount are reserved split fields.\nThe platform has no per-media/per-request/discount source yet, so they\nare null rather than fabricated zeros and do not reconcile against\ntotal_amount.", "type": "string", "x-nullable": true }, "other_amount": { "type": "string" }, "output_amount": { "type": "string" }, "period": { "$ref": "#/definitions/openapi.UsagePeriod" }, "request_amount": { "type": "string", "x-nullable": true }, "status": { "description": "Status is set only for a status-filtered read (estimated/settled/pending/\nreversed); the default read omits it.", "type": "string" }, "tenant_id": { "type": "string" }, "total_amount": { "description": "TotalAmount is authoritative: it is the customer charge actually booked.\nInput/Output/Cache split the component detail upstream publishes. Any\nremainder (per-call/media/request add-ons, or rate cards that publish no\ncomponent detail) is reported as OtherAmount rather than folded into a\ncomponent or silently dropped.", "type": "string" } } }, "openapi.ExportCreateRequest": { "type": "object", "required": [ "kind" ], "properties": { "api_key_id": { "type": "string" }, "cursor": { "type": "string" }, "format": { "type": "string", "enum": [ "csv", "json" ] }, "from": { "type": "string" }, "granularity": { "type": "string", "enum": [ "hour", "day", "month" ] }, "group_by": { "type": "string", "enum": [ "none", "model", "workspace", "member", "api_key" ] }, "kind": { "type": "string", "enum": [ "usage", "cost", "generations" ] }, "limit": { "description": "Limit/Cursor page the SOURCE data: one job exports at most one page.\nDefault 200, max 1000. next_cursor on the job points at the next page.", "type": "integer" }, "model": { "type": "string" }, "timezone": { "type": "string" }, "to": { "type": "string" }, "workspace_id": { "type": "string" } } }, "openapi.ExportJobView": { "type": "object", "properties": { "completed_at": { "type": "string" }, "created_at": { "type": "string" }, "download_url": { "type": "string" }, "error": { "type": "string" }, "expires_at": { "type": "string" }, "format": { "type": "string" }, "has_more": { "type": "boolean" }, "id": { "type": "string" }, "kind": { "type": "string" }, "next_cursor": { "type": "string" }, "row_count": { "type": "integer" }, "status": { "type": "string", "enum": [ "pending", "running", "succeeded", "failed", "expired" ] } } }, "openapi.ExportListResponse": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/definitions/openapi.ExportJobView" } }, "next_cursor": { "type": "string" } } }, "openapi.GenerationBilling": { "type": "object", "properties": { "billing_items": { "description": "BillingItems are the published price components of the settled charge.\nTheir sum equals settled_amount for a flat call; addons are itemized\nrather than folded into a component.", "type": "array", "items": { "$ref": "#/definitions/openapi.GenerationBillingItem" } }, "billing_status": { "type": "string" }, "currency": { "type": "string" }, "estimated_amount": { "description": "EstimatedAmount is the pre-authorization reservation (billing_detail\nreserved_amount), not a prediction of the final charge.", "type": "string" }, "price_version": { "description": "PriceVersion is the applied price-card version (billing_detail price.version).", "type": "integer" }, "settled_amount": { "type": "string" } } }, "openapi.GenerationBillingItem": { "type": "object", "properties": { "amount": { "type": "string" }, "currency": { "type": "string" }, "kind": { "type": "string", "enum": [ "input", "output", "cache", "addon", "other" ] } } }, "openapi.GenerationContent": { "type": "object", "properties": { "available": { "type": "boolean" }, "body_b64": { "type": "string" }, "content": { "description": "Content mirrors body_b64 for clients that read a single payload field; it\nis explicitly null (not an empty string) when nothing was stored.", "type": "string" }, "content_type": { "type": "string" }, "encoding": { "type": "string", "enum": [ "base64" ] }, "kind": { "type": "string", "enum": [ "request", "response" ] }, "reason": { "description": "Reason is set only when Available=false: \"not_stored\" means the workspace\nhad call-time logging off (or the payload was not retained).", "type": "string" }, "size": { "type": "integer" }, "truncated": { "type": "boolean" } } }, "openapi.GenerationDetail": { "type": "object", "properties": { "api_key_id": { "type": "string" }, "billing": { "$ref": "#/definitions/openapi.GenerationBilling" }, "completed_at": { "type": "string" }, "created_at": { "type": "string" }, "error_class": { "type": "string" }, "error_reason": { "type": "string" }, "finish_reason": { "type": "string" }, "generation_id": { "description": "GenerationID is the billing session id (the billing fact key). It can be\nused with /generations/by-billing-session/{id}.", "type": "string" }, "http_status": { "type": "integer" }, "id": { "type": "string" }, "latency": { "$ref": "#/definitions/openapi.GenerationLatency" }, "model_requested": { "type": "string" }, "model_used": { "description": "ModelUsed is the upstream model the router actually sent the call to. It\ncan differ from model_requested when the catalog maps a public key onto a\nsupplier-specific spelling; it is omitted unless the deployment enables\nthe model_used switch.", "type": "string" }, "protocol": { "description": "Protocol is the wire endpoint identifier the call used. Model calls carry\nvalues like \"openai.chat_completions\"; MCP tool calls carry \"/mcp\", so the\nfield is an endpoint id, not always a protocol family.", "type": "string" }, "provider_attempts": { "description": "ProviderAttempts/RetryCount come from runtime_detail.attempt_count:\nattempts = upstream instances tried, retries = attempts - 1. Omitted for\nrows written before the gateway stamped them.", "type": "integer" }, "request_id": { "type": "string" }, "retry_count": { "type": "integer" }, "route_summary": { "description": "RouteSummary is the sanitized routing outcome: how many upstream attempts\nwere made and how the last one ended. It never carries provider names,\ninstance ids or route ids — those stay behind the supplier-identity\nredaction policy.", "allOf": [ { "$ref": "#/definitions/openapi.GenerationRouteSummary" } ] }, "status": { "type": "string" }, "streamed": { "type": "boolean" }, "trace_id": { "type": "string" }, "usage": { "$ref": "#/definitions/openapi.GenerationUsage" }, "vendor": { "type": "string" }, "workspace_id": { "type": "string" } } }, "openapi.GenerationLatency": { "type": "object", "properties": { "generation_ms": { "description": "GenerationMS is the post-first-token span: total_latency_ms - ttft_ms.\nOmitted when either measurement is absent (the gateway did not time it).", "type": "integer" }, "total_latency_ms": { "type": "integer" }, "ttft_ms": { "type": "integer" } } }, "openapi.GenerationRouteSummary": { "type": "object", "properties": { "attempts": { "type": "integer" }, "failovers": { "type": "integer" }, "final_status": { "type": "string" }, "retries": { "type": "integer" } } }, "openapi.GenerationUsage": { "type": "object", "properties": { "cache_write_tokens": { "type": "integer" }, "cached_tokens": { "type": "integer" }, "input_tokens": { "type": "integer" }, "media_units": { "description": "MediaUnits is the per-type media dictionary (image_count /\nvideo_seconds / audio_seconds) the provider actually metered.", "type": "object", "additionalProperties": { "type": "integer" } }, "output_tokens": { "type": "integer" }, "reasoning_tokens": { "description": "ReasoningTokens is the provider-reported thinking/reasoning token count\n(token_detail.thinking). Omitted when the provider does not report one.", "type": "integer" }, "total_tokens": { "type": "integer" } } }, "openapi.ManagedKey": { "type": "object", "properties": { "created_at": { "type": "string" }, "expires_at": { "type": "string" }, "id": { "type": "string" }, "key_type": { "type": "string" }, "last_used_at": { "type": "string" }, "masked": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "spending_limit": { "$ref": "#/definitions/apikey.Limit" }, "status": { "type": "string" } } }, "openapi.ManagedKeyCreateRequest": { "type": "object", "required": [ "name", "workspace_id" ], "properties": { "expires_at": { "type": "string" }, "key_type": { "description": "Public management keys are the caller's own (personal). Member/service\nkeys need attribution fields the public surface does not expose yet.", "type": "string", "enum": [ "personal" ] }, "name": { "type": "string", "maxLength": 64, "minLength": 1 }, "spending_limit": { "$ref": "#/definitions/apikey.Limit" }, "workspace_id": { "type": "string" } } }, "openapi.ManagedKeyCreateResponse": { "type": "object", "properties": { "created_at": { "type": "string" }, "expires_at": { "type": "string" }, "id": { "type": "string" }, "key": { "description": "Key is the only copy of the plaintext; the same Idempotency-Key replays it.", "type": "string" }, "key_type": { "type": "string" }, "last_used_at": { "type": "string" }, "masked": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "spending_limit": { "$ref": "#/definitions/apikey.Limit" }, "status": { "type": "string" } } }, "openapi.ManagedKeyList": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/definitions/openapi.ManagedKey" } }, "next_cursor": { "type": "string" }, "page_size": { "type": "integer" } } }, "openapi.ManagedKeyRotation": { "type": "object", "properties": { "key": { "type": "string" }, "previous_key_active": { "type": "boolean" }, "previous_masked": { "type": "string" }, "rotated_at": { "type": "string" } } }, "openapi.ManagedKeyUpdateRequest": { "type": "object", "properties": { "expires_at": { "type": "string" }, "name": { "type": "string", "maxLength": 64, "minLength": 1 }, "spending_limit": { "type": "object" } } }, "openapi.OpenAPIError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Code is the stable machine-readable identifier for this failure.", "type": "string", "example": "invalid_token" }, "error_class": { "description": "ErrorClass groups codes by the layer that rejected the request.", "type": "string", "enum": [ "invalid_request", "authentication", "authorization", "not_found", "conflict", "rate_limit", "upstream", "internal" ], "example": "authentication" }, "message": { "description": "Message is human-readable and may change; do not branch on it.", "type": "string", "example": "token expired" }, "reason": { "description": "Reason narrows Code when the same code has several causes; omitted when there is none.", "type": "string", "example": "expired" }, "request_id": { "description": "RequestID is echoed in logs and support tickets.", "type": "string", "example": "7be30293-4b03-4691-98af-b0ec2d88ce42" }, "trace_id": { "description": "TraceID joins this request to its distributed trace.", "type": "string", "example": "bf3b7970c390dc9ba3d38bc353075402" } } } } }, "openapi.UsagePeriod": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } } }, "openapi.UsageResponse": { "type": "object", "properties": { "billing_as_of": { "description": "BillingAsOf is the settlement ledger's closed-through watermark: every\nsession created before it is terminal.", "type": "string" }, "data_as_of": { "description": "DataAsOf is the log pipeline's newest event time (global), not the time\nthis request was served.", "type": "string" }, "error": { "description": "Error is set only for a failed tenant in the list form; single-tenant\nreads report failures as a normal OpenAPI error response instead.", "type": "string" }, "is_final": { "description": "IsFinal is true when the requested window ended at least the grace period\nbefore BOTH watermarks: no late log or settlement can still change it.", "type": "boolean" }, "period": { "$ref": "#/definitions/openapi.UsagePeriod" }, "series": { "type": "array", "items": { "$ref": "#/definitions/openapi.UsageSeriesPoint" } }, "summary": { "$ref": "#/definitions/openapi.UsageSummary" }, "tenant_id": { "type": "string" }, "timezone": { "type": "string" } } }, "openapi.UsageSeriesPoint": { "type": "object", "properties": { "bucket_start": { "type": "string" }, "cache_write_tokens": { "type": "integer" }, "cached_tokens": { "type": "integer" }, "charged_amount": { "type": "string" }, "error_count": { "type": "integer" }, "group_key": { "type": "string" }, "group_label": { "type": "string" }, "input_tokens": { "type": "integer" }, "media_units": { "description": "MediaUnits is the per-type media dictionary (image_count / video_seconds /\naudio_seconds) summed over the bucket; omitted when no media was metered.", "type": "object", "additionalProperties": { "type": "integer" } }, "output_tokens": { "type": "integer" }, "reasoning_tokens": { "type": "integer" }, "request_count": { "type": "integer" }, "success_count": { "type": "integer" }, "tokens": { "description": "Tokens is the bucket total; the breakdown below uses the same bucket.", "type": "integer" } } }, "openapi.UsageSummary": { "type": "object", "properties": { "cached_tokens": { "type": "integer" }, "charged_amount": { "type": "string" }, "currency": { "type": "string" }, "error_count": { "description": "ErrorCount counts failed + rejected calls. A guardrail-blocked call is\nneither a success nor an upstream error, so request_count may exceed\nsuccess_count + error_count.", "type": "integer" }, "input_tokens": { "type": "integer" }, "media_units": { "description": "MediaUnits is the per-type media dictionary over the whole window.", "type": "object", "additionalProperties": { "type": "integer" } }, "output_tokens": { "type": "integer" }, "reasoning_tokens": { "type": "integer" }, "request_count": { "type": "integer" }, "success_count": { "type": "integer" } } } }, "securityDefinitions": { "BearerPAT": { "description": "个人 Access Token，形如 `Bearer mgpat_...`。", "type": "apiKey", "name": "Authorization", "in": "header" } } }