{"openapi":"3.1.0","info":{"title":"Router One API","description":"# Router One API\n\nRouter One 提供 **OpenAI 兼容**的统一模型调用接口。通过智能路由、自动故障转移和成本管控，让团队安全、可控、低成本地在生产环境运行 LLM 工作负载。\n\n> 直接调 LLM = 黑盒；通过 Router One 调 LLM = 有账本、有轨迹、有管控。\n\n---\n\n## 快速开始\n\n只需 3 步即可开始使用 Router One API：\n\n### 1. 获取 API Key\n\n登录 [Router One 控制台](https://router.one) 创建 API Key（格式 `sk-xxx`）。\n\n### 2. 发送第一个请求\n\n```bash\ncurl https://api.router.one/v1/chat/completions \\\n  -H \"Authorization: Bearer sk-your-api-key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"auto\",\n    \"messages\": [{\"role\": \"user\", \"content\": \"你好\"}]\n  }'\n```\n\n将 `model` 设为 `auto` 时，网关用规则加一个轻量分类器把请求分到低、中、高三档之一，再用该档服务端维护的模型列表中的模型处理；可选的 `X-Route-Session` 请求头能让同一段对话在一段时间内保持同一选择。你也可以指定具体模型如 `openai/gpt-5.5`、`anthropic/claude-sonnet-5` 等——模型 ID 以目录为准。指定了模型的请求由该模型处理：某条线路出现 429、5xx 或超时时，会换到同一模型的另一条线路重试；持续报上游错误的线路会被自动排到最后，恢复后再回到正常顺序。\n\n### 3. 处理响应\n\n```json\n{\n  \"id\": \"chatcmpl-abc123\",\n  \"object\": \"chat.completion\",\n  \"model\": \"anthropic/claude-sonnet-4.6\",\n  \"choices\": [{\n    \"index\": 0,\n    \"message\": { \"role\": \"assistant\", \"content\": \"你好！有什么可以帮你的？\" },\n    \"finish_reason\": \"stop\"\n  }],\n  \"usage\": { \"prompt_tokens\": 9, \"completion_tokens\": 12, \"total_tokens\": 21 }\n}\n```\n\n响应中的 `model` 是实际承接请求的目录模型 ID——即使请求写的是 `auto`，这里也是具体 ID。\n\n---\n\n## 认证方式\n\n所有 API 请求需要在 `Authorization` Header 中携带 Bearer Token：\n\n```\nAuthorization: Bearer sk-your-api-key\n```\n\nAPI Key 在 [Router One 控制台](https://router.one) 中创建和管理。每把 Key 可设独立的 maxSpend 消费上限和过期时间；rateLimit 与 tokenLimitTpm 按平台默认值生效，可申请调高。\n\n---\n\n## 基础 URL\n\n| 环境 | 地址 |\n|------|------|\n| **生产环境** | `https://api.router.one` |\n\n---\n\n## 请求格式\n\n- 所有请求使用 **JSON** 格式（`Content-Type: application/json`）\n- API 完全兼容 **OpenAI Chat Completions** 格式，现有代码只需替换 `base_url` 即可接入\n- 支持流式（SSE）和非流式两种响应模式\n\n---\n\n## 错误处理\n\nAPI 返回标准 HTTP 状态码，错误响应包含结构化的错误信息：\n\n```json\n{\n  \"error\": {\n    \"message\": \"invalid api key\",\n    \"type\": \"authentication_error\",\n    \"code\": \"AUTH_INVALID_API_KEY\",\n    \"request_id\": \"290dd478f91d8aec68f7535e871376eb\"\n  }\n}\n```\n\n| 状态码 | 说明 | 处理建议 |\n|--------|------|----------|\n| `401` | API Key 无效或缺失 | 检查 Authorization Header |\n| `402` | 余额不足或 API Key 消费上限已达 | 到 /deposit 充值，或调高该 Key 的 maxSpend——充值不会解除 Key 上限 |\n| `429` | 触发限流或配额 | 读 `Retry-After` 退避；`code` 指明命中哪一种——`RATE_LIMIT_EXCEEDED`（每分钟请求数）、`TOKEN_QUOTA_EXCEEDED`（每分钟或每日 token）、`SUBSCRIPTION_QUOTA_EXCEEDED`（订阅每日配额）；429 与余额、Key 上限无关 |\n| `500` | 服务器内部错误 | 稍后重试，如持续出现请联系支持 |\n\n错误体都带 `request_id`，报障时请一并提供。`/v1/messages` 把同样的字段放进 Anthropic 外层结构，401、429 等网关层错误把 `request_id` 放在顶层：`{\"type\":\"error\",\"error\":{…},\"request_id\":\"…\"}`。\n\n### 错误码\n\n`type` 取值为 `invalid_request_error`、`authentication_error`、`authorization_error`、`rate_limit_error`、`billing_error`、`api_error`、`service_unavailable` 之一；`code` 为机器可读的大写下划线码：\n\n| 错误码 | 状态码 | 含义 |\n|------|------|------|\n| `INVALID_REQUEST` | 400 | 请求体格式错误、模型不可用，或该模型不在此端点服务 |\n| `CONTENT_FILTERED` | 400 | prompt 被内容审核拒绝（图片与视频端点） |\n| `AUTH_INVALID_API_KEY` | 401 | API Key 无效或缺失 |\n| `INSUFFICIENT_BALANCE` | 402 | 钱包余额耗尽 |\n| `API_KEY_SPEND_CAP_EXCEEDED` | 402 | 该 Key 的 maxSpend 已用尽——这是按 Key 的预算上限，不是限流 |\n| `AUTH_FORBIDDEN` | 403 | 该 Key 无权执行此操作 |\n| `RESOURCE_NOT_FOUND` | 404 | 路径或资源不存在 |\n| `RATE_LIMIT_EXCEEDED` | 429 | 每分钟请求数超限 |\n| `TOKEN_QUOTA_EXCEEDED` | 429 | 每分钟或每日 token 配额超限 |\n| `SUBSCRIPTION_QUOTA_EXCEEDED` | 429 | 订阅套餐每日配额超限 |\n| `INTERNAL_ERROR` | 500 | 网关侧故障，稍后重试 |\n| `MODERATION_UNAVAILABLE` | 502 | 内容审核服务暂时无法审查 prompt（图片与视频端点），稍后重试 |\n| `PROVIDER_UNAVAILABLE` | 503 / 504 | 上游供给不可用或超时，稍后重试 |\n\n---\n\n## 限流与响应头\n\n对话类端点（`/v1/chat/completions`、`/v1/messages`、`/v1/responses`）的响应会带上当前限额状态，成功与 `429` 都会返回：\n\n| 响应头 | 含义 |\n|--------|------|\n| `RateLimit-Limit` / `RateLimit-Remaining` / `RateLimit-Reset` | 每分钟请求数上限、剩余额度、距窗口重置的秒数 |\n| `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset` | 同样三个值的 `X-` 前缀写法，供只读这种形式的客户端使用 |\n| `X-TokenLimit-TPM` / `X-TokenLimit-TPM-Remaining` / `X-TokenLimit-TPM-Reset` | 每分钟 token 上限、剩余额度、距重置的秒数 |\n| `X-TokenQuota-Day` / `X-TokenQuota-Day-Remaining` / `X-TokenQuota-Day-Reset` | 仅在启用每日 token 配额时出现；重置时间为 Unix 时间戳（秒） |\n| `X-Subscription-Quota-Day-Limit-Requests` / `-Limit-Tokens` / `-Remaining-Requests` / `-Remaining-Tokens` / `X-Subscription-Quota-Day-Reset` | 仅在订阅套餐每日配额触发的 `429` 上出现；重置时间为 Unix 时间戳（秒） |\n| `Retry-After` | 建议等待的秒数。请按它退避，不要自己猜 |\n\n图片、视频与模型列表端点按 Key 限流，但不返回上述响应头。","version":"1.0.0","contact":{"name":"Router One","url":"https://router.one"}},"servers":[{"url":"https://api.router.one","description":"Production"}],"tags":[{"name":"Chat","description":"对话与文本生成接口。支持 OpenAI Chat Completions、OpenAI Responses，以及 Claude / Anthropic Messages 兼容请求。将 `model` 设为 `auto` 可启用智能路由。"},{"name":"Models","description":"模型目录接口。返回当前 Key 可调用的模型 ID 及其能力与牌价，与 [Router One 模型广场](https://router.one/zh/models) 同源。"},{"name":"Account","description":"账户接口。查询当前 API Key 所属账号的预付余额——用于服务端余额监控，在余额耗尽前及时充值。"},{"name":"Images","description":"图片生成与图片编辑接口。支持根据文本提示词生成图片，也支持通过 `/v1/images/edits` 按文本指令改写参考图（图生图）；可选返回 URL 或 base64 编码，按实际生成张数计费。\n\n在 [Router One 模型广场](https://router.one/zh/models) 可查询当前支持图片生成与图生图的模型列表。"},{"name":"Videos","description":"视频生成接口。视频生成耗时较长（数十秒到几分钟），采用异步任务模式：先调用提交接口拿到 `task_id`，再通过轮询接口获取生成进度和最终结果 URL。\n\n支持纯文本生视频与参考图生视频。具体可用模型和参数范围请在[模型广场](https://router.one/zh/models)查询。"}],"security":[{"BearerAuth":[]}],"paths":{"/v1/chat/completions":{"post":{"operationId":"createChatCompletion","summary":"创建聊天补全","description":"创建一个聊天补全请求：OpenAI Chat Completions 兼容端点，一个 base URL 接入 30+ 模型，支持流式和非流式响应，`model: auto` 走智能路由。\n\n设置 `model` 为 `auto` 时，Router One 会按当前网关策略从服务端候选集中选择。\n\n耗时较长的 `stream: false` 调用会保持连接（截至 2026-10-09）：约 25 秒后网关先提交 HTTP 200，并在补全结果就绪前写入 JSON 前导空白，此后的失败以 HTTP 200 加顶层 `error` 对象返回——先判断 `error`，再读 `choices`；需要几分钟的生成请用 `stream: true`。","tags":["Chat"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionRequest"},"examples":{"basic":{"summary":"基础请求","value":{"model":"auto","messages":[{"role":"user","content":"你好"}]}},"with-system-prompt":{"summary":"带系统提示词","value":{"model":"auto","messages":[{"role":"system","content":"你是一个有帮助的助手。"},{"role":"user","content":"介绍一下 Router One"}],"temperature":0.7,"max_tokens":1024}},"streaming":{"summary":"流式响应","value":{"model":"auto","stream":true,"messages":[{"role":"user","content":"写一首诗"}]}},"json-schema":{"summary":"结构化输出（json_schema）","value":{"model":"auto","messages":[{"role":"user","content":"抽取城市和日期：9 月 3 日在上海开会。"}],"response_format":{"type":"json_schema","json_schema":{"name":"meeting","strict":true,"schema":{"type":"object","properties":{"city":{"type":"string"},"date":{"type":"string"}},"required":["city","date"],"additionalProperties":false}}}}}}}}},"responses":{"200":{"description":"成功返回聊天补全结果。当 `stream: false` 时返回 JSON 对象；当 `stream: true` 时返回 SSE 事件流。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionResponse"},"example":{"id":"chatcmpl-abc123","object":"chat.completion","created":1700000000,"model":"anthropic/claude-sonnet-4.6","choices":[{"index":0,"message":{"role":"assistant","content":"你好！有什么我可以帮你的吗？"},"finish_reason":"stop"}],"usage":{"prompt_tokens":9,"completion_tokens":12,"total_tokens":21}}},"text/event-stream":{"schema":{"type":"string","description":"SSE 事件流。每个事件以 `data: ` 开头，包含一个 JSON 对象。流结束时发送 `data: [DONE]`。"},"example":"data: {\"id\":\"chatcmpl-abc123\",\"object\":\"chat.completion.chunk\",\"created\":1700000000,\"model\":\"openai/gpt-5.5\",\"choices\":[{\"index\":0,\"delta\":{\"role\":\"assistant\",\"content\":\"你\"},\"finish_reason\":null}]}\n\ndata: {\"id\":\"chatcmpl-abc123\",\"object\":\"chat.completion.chunk\",\"created\":1700000000,\"model\":\"openai/gpt-5.5\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"好\"},\"finish_reason\":null}]}\n\ndata: {\"id\":\"chatcmpl-abc123\",\"object\":\"chat.completion.chunk\",\"created\":1700000000,\"model\":\"openai/gpt-5.5\",\"choices\":[{\"index\":0,\"delta\":{},\"finish_reason\":\"stop\"}]}\n\ndata: [DONE]\n"}}},"400":{"description":"请求无效——模型发到了不服务它的端点（消息里会写明应走的路径），或请求体格式错误，例如 response_format 外层结构不完整","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"response_format.json_schema.name is required","type":"invalid_request_error","code":"INVALID_REQUEST","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}},"401":{"description":"认证失败 — API Key 无效或缺失","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"invalid api key","type":"authentication_error","code":"AUTH_INVALID_API_KEY","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}},"402":{"description":"余额不足或 API Key 消费上限已达 — billing_error，不是限流","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"insufficient_balance":{"summary":"钱包余额耗尽","value":{"error":{"message":"insufficient balance: top up at https://router.one/deposit","type":"billing_error","code":"INSUFFICIENT_BALANCE","request_id":"290dd478f91d8aec68f7535e871376eb"}}},"api_key_spend_cap":{"summary":"该 Key 的 maxSpend 已用尽","value":{"error":{"message":"api key spend cap reached: raise or clear this key's maxSpend at https://router.one/dashboard — this is a per-key budget cap, not a rate limit, and topping up the wallet does not lift it","type":"billing_error","code":"API_KEY_SPEND_CAP_EXCEEDED","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}}}},"429":{"description":"触发限流或配额 — 每分钟请求数超限 code 为 RATE_LIMIT_EXCEEDED，每分钟或每日 token 配额为 TOKEN_QUOTA_EXCEEDED，订阅套餐每日配额为 SUBSCRIPTION_QUOTA_EXCEEDED；读 Retry-After 退避。控制台 → 日志里有记录的 429，是网关重试之后上游仍返回的。网关限额会在调用任何模型之前拒绝请求，所以这种 429 没有日志记录，X-RateLimit-Scope 为 api_key（这把 Key）、subject（整个账户）或 subject_model（账户在单个模型上的用量），并按同一频率反复出现；可发邮件到 support@router.one 申请调高；upstream_provider 是模型厂商的限制。在输出任何内容之前就撞上上游限流的流式请求也可能没有日志记录，所以没有记录、又会自行消失的突发 429 同样指向上游","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"rate limit exceeded","type":"rate_limit_error","code":"RATE_LIMIT_EXCEEDED","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"internal error","type":"api_error","code":"INTERNAL_ERROR","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}}}}},"/v1/messages":{"post":{"operationId":"createMessage","summary":"创建消息（Messages）","description":"创建 Claude / Anthropic Messages 兼容请求（Claude Code 使用的形态），供当前目录中的 Claude 系列模型与 DeepSeek ID 使用，支持流式与非流式。其他对话模型请走 /v1/chat/completions。模型被发送到不支持的端点时，会在调用任何模型之前被拒绝：400 invalid_request_error，消息为 model '<id>' must be called via /v1/chat/completions。错误体采用 Anthropic 外层结构 {\"type\":\"error\",\"error\":{type,message,code}}，不是其他端点的 OpenAI {\"error\":{…}} 形状；网关自身返回的错误（例如 401、429）另带顶层 request_id，每个响应都带 X-Request-ID 响应头。\n\nfunction 工具按原样转发（`tools` 带 `input_schema`、`tool_choice`；`tool_use` / `tool_result` 块可往返）；只有 Claude Opus 5.5（`claude-opus-5-5` 或 `anthropic/claude-opus-5.5`）例外：对这个模型，`tool_choice` 的 `any` 或 `tool` 会按 `auto` 发送，模型可能直接用文字回答而不调用工具。模型是否接受强制 `tool_choice` 由厂商决定（见 Anthropic 的工具调用文档，2026-10-09 核对）。Anthropic 服务端工具：`web_search` 与 `code_execution`（含 `bash_*` / `text_editor_*` 子工具与跨轮次容器复用）被接受并按该模型公示的 token 单价计量（容器时长不按次透传计费）；`web_fetch`、`mcp_toolset`、`mcp_servers` 会在调用任何模型之前被拒绝，返回 400 invalid_request_error。\n\n耗时较长的 `stream: false` 调用会保持连接（截至 2026-10-09）：约 25 秒后网关先提交 HTTP 200，并在 Message 就绪前写入 JSON 前导空白，此后的失败以 HTTP 200 加上述错误外层结构返回——先判断 `type`，再读 `content`；需要几分钟的生成请用 `stream: true`。","tags":["Chat"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageRequest"},"examples":{"basic":{"summary":"基础请求","value":{"model":"auto","max_tokens":1024,"messages":[{"role":"user","content":"你好"}]}},"streaming":{"summary":"流式响应","value":{"model":"auto","max_tokens":1024,"stream":true,"messages":[{"role":"user","content":"写一段产品介绍"}]}}}}}},"responses":{"200":{"description":"成功返回 Messages API 兼容响应。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageResponse"},"example":{"id":"msg_abc123","type":"message","role":"assistant","model":"anthropic/claude-sonnet-5","content":[{"type":"text","text":"你好！有什么我可以帮你的吗？"}],"stop_reason":"end_turn","usage":{"input_tokens":9,"output_tokens":12}}}}},"400":{"description":"请求无效——模型不支持当前端点（请走 /v1/chat/completions）、请求体格式错误，或被拒绝的服务端工具（web_fetch、mcp_toolset、mcp_servers）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnthropicErrorResponse"},"example":{"type":"error","error":{"type":"invalid_request_error","message":"model 'openai/gpt-5.5' must be called via /v1/chat/completions","code":"INVALID_REQUEST"}}}}},"401":{"description":"认证失败 — API Key 无效或缺失","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnthropicErrorResponse"},"example":{"type":"error","error":{"type":"authentication_error","message":"invalid api key","code":"AUTH_INVALID_API_KEY"},"request_id":"86bc1f64e4bcdfc3cc516e51cc419418"}}}},"402":{"description":"余额不足或 API Key 消费上限已达 — billing_error，不是限流","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnthropicErrorResponse"},"examples":{"insufficient_balance":{"summary":"钱包余额耗尽","value":{"type":"error","error":{"type":"billing_error","message":"insufficient balance: top up at https://router.one/deposit"}}},"api_key_spend_cap":{"summary":"该 Key 的 maxSpend 已用尽","value":{"type":"error","error":{"type":"billing_error","message":"api key spend cap reached: raise or clear this key's maxSpend at https://router.one/dashboard — this is a per-key budget cap, not a rate limit, and topping up the wallet does not lift it"}}}}}}},"429":{"description":"触发限流或配额 — 每分钟请求数超限 code 为 RATE_LIMIT_EXCEEDED，每分钟或每日 token 配额为 TOKEN_QUOTA_EXCEEDED，订阅套餐每日配额为 SUBSCRIPTION_QUOTA_EXCEEDED；读 Retry-After 退避。控制台 → 日志里有记录的 429，是网关重试之后上游仍返回的。网关限额会在调用任何模型之前拒绝请求，所以这种 429 没有日志记录，X-RateLimit-Scope 为 api_key（这把 Key）、subject（整个账户）或 subject_model（账户在单个模型上的用量），并按同一频率反复出现；可发邮件到 support@router.one 申请调高；upstream_provider 是模型厂商的限制","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnthropicErrorResponse"},"example":{"type":"error","error":{"type":"rate_limit_error","message":"rate limit exceeded","code":"RATE_LIMIT_EXCEEDED"},"request_id":"86bc1f64e4bcdfc3cc516e51cc419418"}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnthropicErrorResponse"},"example":{"type":"error","error":{"type":"api_error","message":"internal error","code":"INTERNAL_ERROR"},"request_id":"86bc1f64e4bcdfc3cc516e51cc419418"}}}}}}},"/v1/responses":{"post":{"operationId":"createResponse","summary":"创建响应（Responses）","description":"创建一个 OpenAI Responses API 请求——即 Codex CLI 使用的形态，当前目录中的 GPT 系列模型、DeepSeek ID 与 Grok 对话模型原生走该端点。文本输入、指令、流式与 function 工具按原样转发；custom 工具、previous_response_id / conversation / prompt、hosted 工具（file_search、code_interpreter、computer_use、mcp、web_search）与 file_id / file_url 输入块在原生走 Responses 线协议的模型上可用，按该模型公示单价计费。以下请求会返回 400 invalid_request：image_generation 工具与 image_generation_call 输入项（请改用 /v1/images/generations）、background: true。Claude 家族的模型 ID 不在该端点服务：指定它会在调用任何模型之前被拒绝，返回 400 invalid_request_error，消息为 model 'anthropic/claude-opus-5' must be called via /v1/messages or /v1/chat/completions；使用 model: auto 时候选集合本身不含 Claude，请求由其他系列承接。\n\n耗时较长的 `stream: false` 调用会保持连接（截至 2026-10-09）：约 25 秒后网关先提交 HTTP 200，并在响应就绪前写入 JSON 前导空白，此后的失败以 HTTP 200 加顶层 `error` 对象返回——先判断 `error`，再读 `output`；需要几分钟的生成请用 `stream: true`。","tags":["Chat"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesRequest"},"examples":{"basic":{"summary":"基础请求","value":{"model":"openai/gpt-5.5","input":"用一句话介绍 Router One"}},"withInstructions":{"summary":"带指令","value":{"model":"openai/gpt-5.5","instructions":"你是一个简洁的技术文档助手。","input":"解释智能路由。"}}}}}},"responses":{"200":{"description":"成功返回 Responses API 兼容响应。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesResponse"},"example":{"id":"resp_abc123","object":"response","created_at":1700000000,"status":"completed","model":"openai/gpt-5.5","output_text":"Router One 是统一的 LLM API 网关。","output":[{"role":"assistant","content":[{"type":"output_text","text":"Router One 是统一的 LLM API 网关。"}]}],"usage":{"input_tokens":12,"output_tokens":10,"total_tokens":22}}}}},"400":{"description":"请求无效——使用了网关不提供的 Responses 特性（background、image_generation 工具），或该模型不在此端点服务","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"model 'anthropic/claude-opus-5' must be called via /v1/messages or /v1/chat/completions","type":"invalid_request_error","code":"INVALID_REQUEST","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}},"401":{"description":"认证失败 — API Key 无效或缺失","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"invalid api key","type":"authentication_error","code":"AUTH_INVALID_API_KEY","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}},"402":{"description":"余额不足或 API Key 消费上限已达 — billing_error，不是限流","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"insufficient_balance":{"summary":"钱包余额耗尽","value":{"error":{"message":"insufficient balance: top up at https://router.one/deposit","type":"billing_error","code":"INSUFFICIENT_BALANCE","request_id":"290dd478f91d8aec68f7535e871376eb"}}},"api_key_spend_cap":{"summary":"该 Key 的 maxSpend 已用尽","value":{"error":{"message":"api key spend cap reached: raise or clear this key's maxSpend at https://router.one/dashboard — this is a per-key budget cap, not a rate limit, and topping up the wallet does not lift it","type":"billing_error","code":"API_KEY_SPEND_CAP_EXCEEDED","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}}}},"429":{"description":"触发限流或配额 — 每分钟请求数超限 code 为 RATE_LIMIT_EXCEEDED，每分钟或每日 token 配额为 TOKEN_QUOTA_EXCEEDED，订阅套餐每日配额为 SUBSCRIPTION_QUOTA_EXCEEDED；读 Retry-After 退避。控制台 → 日志里有记录的 429，是网关重试之后上游仍返回的。网关限额会在调用任何模型之前拒绝请求，所以这种 429 没有日志记录，X-RateLimit-Scope 为 api_key（这把 Key）、subject（整个账户）或 subject_model（账户在单个模型上的用量），并按同一频率反复出现；可发邮件到 support@router.one 申请调高；upstream_provider 是模型厂商的限制","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"rate limit exceeded","type":"rate_limit_error","code":"RATE_LIMIT_EXCEEDED","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"internal error","type":"api_error","code":"INTERNAL_ERROR","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}}}}},"/v1/models":{"get":{"operationId":"listModels","summary":"列出可用模型","description":"列出当前 API Key 可调用的模型，每一项都带有请求时要填的模型 `id`，以及能力、上下文窗口与牌价字段。从网关获取模型列表的客户端会调用它，例如开启了网关模型发现的 Claude Code（CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1，按 Claude Code 2.1.295 的环境变量与网关协议文档，2026-10-09 核对）。额外的 `models` 数组按 Codex CLI 模型目录的字段格式重复同一份目录。响应带 `ETag`——回传 `If-None-Match`，目录未变时返回 `304 Not Modified` 且无响应体。模型 ID 区分大小写，请从响应或模型目录复制。","tags":["Models"],"parameters":[{"name":"If-None-Match","in":"header","required":false,"description":"上一次响应返回的 `ETag`。匹配时返回 304 Not Modified。","schema":{"type":"string"}}],"responses":{"200":{"description":"当前 Key 的模型目录","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"固定为 `list`。"},"data":{"type":"array","description":"当前 Key 可调用的每个模型一项。","items":{"type":"object","properties":{"id":{"type":"string","description":"请求 `model` 字段要填的模型 ID，区分大小写。"},"object":{"type":"string","enum":["model"]}}}}}},"example":{"object":"list","data":[{"id":"anthropic/claude-sonnet-5","object":"model","capabilities":["chat","streaming","tool_calling","vision"],"max_tokens":1048576,"category":"text","pricing_mode":"token"}]}}}},"304":{"description":"目录自上次 ETag 起未变化，无响应体"},"401":{"description":"认证失败 — API Key 无效或缺失","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"invalid api key","type":"authentication_error","code":"AUTH_INVALID_API_KEY","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}}}}},"/v1/balance":{"get":{"operationId":"getBalance","summary":"查询余额","description":"返回当前 API Key 所属账号的预付余额，单位 USD。用于服务端监控：定时轮询，在余额耗尽前充值。返回实时值（`Cache-Control: no-store`）。低余额告警请看 `balance`——当前可直接消费的金额，已包含赠送余额。请求进行中时，网关会把预估费用暂时预留在 `reserved_balance`；每个请求结算后，多预留的部分会退回 `balance`，因此高并发时 `balance` 会短暂下探，而 `total_balance` 保持平稳。本接口有独立限流：每个 Key 每分钟 60 次，不占用推理请求的限流配额。","tags":["Account"],"responses":{"200":{"description":"账号余额","content":{"application/json":{"schema":{"type":"object","required":["object","currency","balance","reserved_balance","total_balance"],"properties":{"object":{"type":"string","enum":["balance"],"description":"固定为 `balance`。"},"currency":{"type":"string","enum":["USD"],"description":"固定为 `USD`。"},"balance":{"type":"number","description":"当前可消费余额（USD）。低余额告警请使用此字段。"},"reserved_balance":{"type":"number","description":"进行中请求暂时预留的金额（USD）。每个请求结算后，多预留的部分退回 `balance`。"},"total_balance":{"type":"number","description":"`balance` + `reserved_balance`（USD）。用于对账。"}}},"example":{"object":"balance","currency":"USD","balance":12.345678,"reserved_balance":0.5,"total_balance":12.845678}}}},"401":{"description":"认证失败 — API Key 无效或缺失","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"invalid api key","type":"authentication_error","code":"AUTH_INVALID_API_KEY","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}},"429":{"description":"触发限流 — 该 Key 每分钟超过 60 次请求；请退避后重试","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"rate limit exceeded","type":"rate_limit_error","code":"RATE_LIMIT_EXCEEDED","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}}}}},"/v1/images/generations":{"post":{"operationId":"createImageGeneration","summary":"创建图片生成","description":"根据文本提示词生成图片。该接口为同步接口，请求会在图片生成完成后返回；典型耗时 5-30 秒，建议客户端 HTTP 超时设置不少于 60 秒。\n\n响应中的 `data` 数组长度等于实际生成的图片数量，按张数计费。当 `response_format` 为 `url` 时返回的图片链接具有有效期（通常 1 小时），如需长期保存请下载或转存到自有存储。","tags":["Images"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageGenerationRequest"},"examples":{"basic":{"summary":"基础请求","value":{"model":"gpt-image-2","prompt":"一只戴着宇航员头盔的橙色小猫，漂浮在星空背景中，电影感打光"}},"with-params":{"summary":"指定尺寸与返回格式","value":{"model":"gpt-image-2","prompt":"极简主义海报，黄色背景上的黑色咖啡杯","n":2,"size":"1024x1024","response_format":"b64_json"}}}}}},"responses":{"200":{"description":"生成成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageGenerationResponse"},"example":{"created":1700000000,"data":[{"url":"https://cdn.router.one/img/abc123.png","revised_prompt":"An orange kitten wearing an astronaut helmet, floating in starry space, cinematic lighting"}]}}}},"400":{"description":"请求参数错误 — 模型不可用、字段格式不合法、prompt 缺失，或 prompt 被内容审核拒绝（code CONTENT_FILTERED）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"requested model is not available","type":"invalid_request_error","code":"INVALID_REQUEST","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}},"401":{"description":"认证失败 — API Key 无效或缺失","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"invalid api key","type":"authentication_error","code":"AUTH_INVALID_API_KEY","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}},"402":{"description":"余额不足或 API Key 消费上限已达 — billing_error，不是限流","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"insufficient_balance":{"summary":"钱包余额耗尽","value":{"error":{"message":"insufficient balance: top up at https://router.one/deposit","type":"billing_error","code":"INSUFFICIENT_BALANCE","request_id":"290dd478f91d8aec68f7535e871376eb"}}},"api_key_spend_cap":{"summary":"该 Key 的 maxSpend 已用尽","value":{"error":{"message":"api key spend cap reached: raise or clear this key's maxSpend at https://router.one/dashboard — this is a per-key budget cap, not a rate limit, and topping up the wallet does not lift it","type":"billing_error","code":"API_KEY_SPEND_CAP_EXCEEDED","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}}}},"429":{"description":"请求频率超限","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"rate limit exceeded","type":"rate_limit_error","code":"RATE_LIMIT_EXCEEDED","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"internal error","type":"api_error","code":"INTERNAL_ERROR","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}},"502":{"description":"内容审核服务不可用 — prompt 无法完成审查时请求会被拒绝而不是放行，稍后重试","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"content moderation unavailable","type":"service_unavailable","code":"MODERATION_UNAVAILABLE","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}},"503":{"description":"上游供给不可用 — 上游侧的鉴权、配额或 5xx 故障统一归一为此状态，稍后重试","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"provider is currently unavailable","type":"service_unavailable","code":"PROVIDER_UNAVAILABLE","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}}}}},"/v1/images/edits":{"post":{"operationId":"createImageEdit","summary":"创建图片编辑（图生图）","description":"根据文本指令改写参考图（图生图）——风格迁移、替换背景、修改主体、局部修复等，参考图以 multipart 文件上传，响应返回 URL 或 base64。与文生图一样是同步接口，请求会在图片生成完成后返回；典型耗时 5-30 秒，建议客户端 HTTP 超时设置不少于 60 秒。\n\n与其他 JSON 接口不同，该接口使用 `multipart/form-data`，参考图以文件形式上传。传一个 `image` 字段即可；所选模型支持多参考图时，可重复传多个 `image` 字段（也接受 `image[]`）。每个文件必须是图片格式，大小不超过 25 MB。\n\n响应结构与计费和文生图一致：`data` 数组长度等于实际生成的图片数量，`url` 方式返回的链接有效期约 1 小时，如需长期保存请下载或转存。","tags":["Images"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/ImageEditRequest"}}}},"responses":{"200":{"description":"生成成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageGenerationResponse"},"example":{"created":1700000000,"data":[{"url":"https://cdn.router.one/img/def456.png"}]}}}},"400":{"description":"请求参数错误 — 缺少 image、prompt 或 model，请求体不是 multipart/form-data，模型不支持图生图，或 prompt 被内容审核拒绝（code CONTENT_FILTERED）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"invalid request body: image is required","type":"invalid_request_error","code":"INVALID_REQUEST","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}},"401":{"description":"认证失败 — API Key 无效或缺失","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"invalid api key","type":"authentication_error","code":"AUTH_INVALID_API_KEY","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}},"402":{"description":"余额不足或 API Key 消费上限已达 — billing_error，不是限流","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"insufficient_balance":{"summary":"钱包余额耗尽","value":{"error":{"message":"insufficient balance: top up at https://router.one/deposit","type":"billing_error","code":"INSUFFICIENT_BALANCE","request_id":"290dd478f91d8aec68f7535e871376eb"}}},"api_key_spend_cap":{"summary":"该 Key 的 maxSpend 已用尽","value":{"error":{"message":"api key spend cap reached: raise or clear this key's maxSpend at https://router.one/dashboard — this is a per-key budget cap, not a rate limit, and topping up the wallet does not lift it","type":"billing_error","code":"API_KEY_SPEND_CAP_EXCEEDED","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}}}},"429":{"description":"请求频率超限","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"rate limit exceeded","type":"rate_limit_error","code":"RATE_LIMIT_EXCEEDED","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"internal error","type":"api_error","code":"INTERNAL_ERROR","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}},"502":{"description":"内容审核服务不可用 — prompt 无法完成审查时请求会被拒绝而不是放行，稍后重试","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"content moderation unavailable","type":"service_unavailable","code":"MODERATION_UNAVAILABLE","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}},"503":{"description":"上游供给不可用 — 上游侧的鉴权、配额或 5xx 故障统一归一为此状态，稍后重试","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"provider is currently unavailable","type":"service_unavailable","code":"PROVIDER_UNAVAILABLE","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}}}}},"/v1/videos/generations":{"post":{"operationId":"submitVideoGeneration","summary":"提交视频生成任务","description":"提交异步视频生成任务：成功响应 `202 Accepted` 并返回 `task_id`，再用 `GET /v1/videos/generations/{task_id}` 轮询；生成通常需要 30 秒到几分钟，取决于模型。流程：\n\n1. 调用本接口提交任务，成功响应 `202 Accepted`，返回 `task_id`。\n2. 客户端使用 `task_id` 调用 `GET /v1/videos/generations/{task_id}` 轮询状态。\n3. 当 `status` 变为 `completed` 时，从响应中读取视频 `url`。\n\n**建议**：轮询间隔不少于 3 秒；不要为整个生成过程设置 HTTP 超时——仅对单次提交/轮询请求设置短超时（如 30 秒）。\n\n**时长与分辨率按模型固定**、按条计价；请求体里的 `duration` / `size` 会被忽略。目录里是否有视频模型见[视频生成页](https://router.one/zh/veo-api-china)；截至 2026-10-01 没有。\n\n**参考图说明**：图生视频模型必须且只能传一张 `image_url`，文生视频模型带图会被拒绝。支持 HTTP(S) URL，单图不超过 20MB；提交后 Router One 会代为下载并安全转存，因此即使图片来自用户上传的临时 URL 也可使用。","tags":["Videos"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoGenerationRequest"},"examples":{"text-to-video":{"summary":"文生视频","value":{"model":"<text-to-video-model-id>","prompt":"海浪轻拍沙滩，黄昏的阳光洒在水面上，慢镜头","aspect_ratio":"16:9"}},"image-to-video":{"summary":"图生视频（单张参考图）","value":{"model":"<image-to-video-model-id>","prompt":"镜头缓慢推进，画面中的人物微微转头","image_url":"https://example.com/portrait.jpg"}}}}}},"responses":{"202":{"description":"任务已接受，进入排队/生成流程","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoSubmitResponse"},"example":{"task_id":"v_8f3a92c1d4e74b6ea0b5f1d29c7e8a01","status":"pending"}}}},"400":{"description":"请求参数错误 — 模型不可用、参考图下载失败、参考图形状不符（文生视频模型拒绝 image_url；图生视频模型必须且只能一张），或 prompt 被内容审核拒绝（code CONTENT_FILTERED）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"reference image exceeds 20MB","type":"invalid_request_error","code":"INVALID_REQUEST","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}},"401":{"description":"认证失败 — API Key 无效或缺失","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"invalid api key","type":"authentication_error","code":"AUTH_INVALID_API_KEY","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}},"402":{"description":"余额不足或 API Key 消费上限已达 — billing_error，不是限流","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"insufficient_balance":{"summary":"钱包余额耗尽","value":{"error":{"message":"insufficient balance: top up at https://router.one/deposit","type":"billing_error","code":"INSUFFICIENT_BALANCE","request_id":"290dd478f91d8aec68f7535e871376eb"}}},"api_key_spend_cap":{"summary":"该 Key 的 maxSpend 已用尽","value":{"error":{"message":"api key spend cap reached: raise or clear this key's maxSpend at https://router.one/dashboard — this is a per-key budget cap, not a rate limit, and topping up the wallet does not lift it","type":"billing_error","code":"API_KEY_SPEND_CAP_EXCEEDED","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}}}},"429":{"description":"请求频率超限","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"rate limit exceeded","type":"rate_limit_error","code":"RATE_LIMIT_EXCEEDED","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}},"502":{"description":"网关侧失败 — 内容审核服务不可用（code MODERATION_UNAVAILABLE），或上游返回空响应","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"empty response from upstream","type":"api_error","code":"INTERNAL_ERROR","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}},"503":{"description":"上游供给不可用 — 上游侧的鉴权、配额或 5xx 故障统一归一为此状态，稍后重试","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"provider is currently unavailable","type":"service_unavailable","code":"PROVIDER_UNAVAILABLE","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}},"504":{"description":"提交任务时上游超时","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"upstream timeout","type":"service_unavailable","code":"PROVIDER_UNAVAILABLE","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}}}}},"/v1/videos/generations/{task_id}":{"get":{"operationId":"getVideoGeneration","summary":"查询视频生成状态","description":"按 `task_id` 查询视频生成任务状态：`pending`、`processing`、`completed`（返回视频 `url`）或 `failed`（返回 `error`），建议轮询间隔不少于 3 秒。\n\n- `pending` — 任务已接受，尚未开始处理\n- `processing` — 正在生成（当前目录中的模型不返回 `progress`）\n- `completed` — 生成完成，读取 `url` 获取视频文件\n- `failed` — 生成失败，读取 `error` 获取原因\n\n建议轮询间隔不少于 3 秒。视频文件 URL 具有有效期（通常 24 小时），如需长期保存请下载或转存到自有存储。","tags":["Videos"],"parameters":[{"name":"task_id","in":"path","required":true,"description":"提交接口返回的任务标识，作为不透明字符串原样回传即可，无需解析其内部结构。","schema":{"type":"string"},"example":"v_8f3a92c1d4e74b6ea0b5f1d29c7e8a01"}],"responses":{"200":{"description":"查询成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoStatusResponse"},"examples":{"processing":{"summary":"生成中","value":{"task_id":"v_8f3a92c1d4e74b6ea0b5f1d29c7e8a01","status":"processing"}},"completed":{"summary":"已完成","value":{"task_id":"v_8f3a92c1d4e74b6ea0b5f1d29c7e8a01","status":"completed","url":"https://cdn.router.one/video/abc123.mp4"}},"failed":{"summary":"失败","value":{"task_id":"v_8f3a92c1d4e74b6ea0b5f1d29c7e8a01","status":"failed","error":"Content policy violation"}}}}}},"401":{"description":"认证失败 — API Key 无效或缺失","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"任务不存在 — 未知、已过期、格式错误或属于其他账号（统一返回 404）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"task not found","type":"invalid_request_error","code":"INVALID_REQUEST","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}},"503":{"description":"轮询时上游供给不可用，按轮询间隔稍后重试","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"provider is currently unavailable","type":"service_unavailable","code":"PROVIDER_UNAVAILABLE","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}},"504":{"description":"轮询时上游超时","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"message":"upstream timeout","type":"service_unavailable","code":"PROVIDER_UNAVAILABLE","request_id":"290dd478f91d8aec68f7535e871376eb"}}}}}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"使用 API Key 进行认证。在 Router One 控制台获取你的 API Key，格式为 `sk-xxx`。"}},"schemas":{"ChatCompletionRequest":{"type":"object","required":["model","messages"],"properties":{"model":{"type":"string","description":"模型 ID。设置为 `auto` 时按网关策略使用服务端候选集，也可指定具体模型如 `openai/gpt-5.5`、`anthropic/claude-sonnet-5` 等（模型 ID 以目录为准）。大多数不带厂商前缀的官方模型名（如 `gpt-5.5`、`claude-sonnet-5`）可作为目录 ID 的别名使用；稳妥起见请从 /models 复制目录 ID。","example":"auto"},"messages":{"type":"array","description":"聊天消息列表，按时间顺序排列。","items":{"$ref":"#/components/schemas/ChatMessage"},"minItems":1},"stream":{"type":"boolean","description":"是否启用流式响应。启用后返回 SSE 事件流。","default":false},"temperature":{"type":"number","description":"采样温度，范围 0-2。较高的值（如 0.8）使输出更随机，较低的值（如 0.2）使输出更确定。","minimum":0,"maximum":2,"default":1},"max_tokens":{"type":"integer","description":"生成的最大 token 数量。推理模型的思考 token 也计入这个上限，请留足余量。","minimum":1},"max_completion_tokens":{"type":"integer","description":"`max_tokens` 在 OpenAI 现行规范中的名称，含义相同，任选其一即可。两者同时传入时以 `max_completion_tokens` 为准。","minimum":1},"top_p":{"type":"number","description":"核采样参数。模型考虑概率质量前 top_p 的 token 结果。","minimum":0,"maximum":1,"default":1},"reasoning_effort":{"type":"string","description":"推理强度提示，如 `low`、`medium`、`high`。按原值转发给模型，Router One 不校验、不改写该值；唯一例外是 Claude Opus 5.5（`claude-opus-5-5` 或 `anthropic/claude-opus-5.5`），该值会映射到 Anthropic 的 `output_config.effort`：`none` 与 `minimal` 记为 `low`，`low` 到 `max` 原样写入，其他取值忽略。支持程度因模型而异：没有该控制项的模型会忽略它或返回 400 invalid_request，使用前先查该模型的目录页。","example":"medium"},"stream_options":{"type":"object","description":"流式响应选项。仅在 `stream: true` 时有效。","properties":{"include_usage":{"type":"boolean","description":"是否在流式响应的最后一个 chunk 中包含 usage 信息。","default":false}}},"web_search_options":{"type":"object","description":"托管联网搜索，仅 `google/gemini-3-flash` 接受：传 `{}`（或等价的 `tools: [{\"type\": \"google_search\"}]` 加 `tool_choice: \"auto\"`），由模型决定是否搜索；实际引用的来源以 `url_citation` annotations 返回（非流式在 `choices[0].message.annotations`，流式在 `choices[0].delta.annotations`），按该模型 token 单价计费。其他模型上该字段按原样转发，由模型自身校验。","properties":{}},"tools":{"type":"array","description":"可供模型调用的工具（函数）声明。支持程度因模型而异，使用前先查该模型的目录页。在 `google/gemini-3-flash` 上数组还可以包含 `{\"type\": \"google_search\"}`（托管搜索，见 `web_search_options`）。","items":{"$ref":"#/components/schemas/ChatTool"}},"tool_choice":{"description":"控制模型如何选择工具。`auto` 由模型自行决定，`none` 关闭工具调用，`required` 强制调用某个工具，传对象并指定函数名则强制调用该函数。模型是否接受强制选择由厂商决定；对 Claude Opus 5.5（`claude-opus-5-5` 或 `anthropic/claude-opus-5.5`），Router One 会把 `required` 或指定函数按 `auto` 发送，模型可能直接用文字回答；要从它拿 JSON，请在 `/v1/messages` 上用 `output_config.format`。","oneOf":[{"type":"string","enum":["none","auto","required"],"description":"预设策略。"},{"type":"object","required":["type","function"],"description":"强制调用指定函数。","properties":{"type":{"type":"string","enum":["function"],"description":"固定为 `function`。"},"function":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"要强制调用的函数名。"}}}}}]},"response_format":{"type":"object","description":"转发给模型的输出格式提示。`json_object` 要求模型回复 JSON；`json_schema` 额外附带一份 JSON Schema。Router One 只校验请求形状——`type` 为 json_schema 而缺少 `json_schema.name` 或 `json_schema.schema` 时，在到达模型前即返回 400 invalid_request——不校验、不修复模型输出。Schema 是否被强制执行取决于模型，支持程度因模型而异，请用目标模型实测。对 Claude 系列 ID，这个字段不是拿到 JSON 的可靠方式——请改在 `/v1/messages` 上用 `output_config.format`。详见[结构化输出指南](https://router.one/zh/llm-structured-outputs)。","required":["type"],"properties":{"type":{"type":"string","enum":["text","json_object","json_schema"],"description":"默认为 `text`。`json_object` 要求返回 JSON 对象；`json_schema` 在支持的模型上把回复约束到 `json_schema.schema`。"},"json_schema":{"type":"object","description":"`type` 为 `json_schema` 时必填。原样转发，包括 `strict` 与 `description`。","required":["name","schema"],"properties":{"name":{"type":"string","description":"schema 的标识名。缺失时返回 400 `response_format.json_schema.name is required`。"},"description":{"type":"string","description":"可选，向模型说明这份 schema 的用途。"},"schema":{"type":"object","description":"回复应遵循的 JSON Schema 对象。缺失时返回 400 `response_format.json_schema.schema is required`。"},"strict":{"type":"boolean","description":"要求模型严格遵循 schema。仅支持 strict 模式的模型会遵守。"}}}}}}},"ChatMessage":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["system","user","assistant","tool"],"description":"消息角色。`system` 为系统提示词，`user` 为用户消息，`assistant` 为助手回复，`tool` 为回传给模型的工具执行结果。"},"content":{"oneOf":[{"type":"string","description":"纯文本消息内容"},{"type":"array","description":"多模态内容（文本 + 图片）","items":{"oneOf":[{"type":"object","required":["type","text"],"properties":{"type":{"type":"string","enum":["text"],"description":"内容类型"},"text":{"type":"string","description":"文本内容"}}},{"type":"object","required":["type","image_url"],"properties":{"type":{"type":"string","enum":["image_url"],"description":"内容类型"},"image_url":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"图片 URL 或 base64 编码的图片数据"}}}}}]}}],"description":"消息内容。可以是字符串或多模态内容数组。"},"name":{"type":"string","description":"可选的参与者名称。"},"tool_calls":{"type":"array","description":"助手请求的工具调用。当 `finish_reason` 为 `tool_calls` 时随 assistant 消息返回；回传结果前先把该消息原样追加进消息列表。","items":{"$ref":"#/components/schemas/ChatToolCall"}},"tool_call_id":{"type":"string","description":"本条消息所回应的工具调用 ID。`tool` 消息必填。"},"refusal":{"type":"string","nullable":true,"description":"拒答正文（OpenAI 风格的 `message.refusal`）。仅在模型明确拒答时出现在响应的 assistant 消息上，此时 `content` 可能为空字符串。请求中传入会被忽略。"}}},"ChatTool":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["function","google_search"],"description":"工具类型。`function`（客户端工具，必须带 `function` 对象）在所有支持工具调用的模型上可用；`google_search`（托管搜索，不带 `function` 对象）仅 `google/gemini-3-flash` 接受。"},"function":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"函数名。模型决定调用该工具时会返回这个名字。","example":"get_weather"},"description":{"type":"string","description":"函数的作用说明。模型依据它判断何时调用。"},"parameters":{"type":"object","description":"以 JSON Schema 对象描述的函数参数。"}}}}},"ChatToolCall":{"type":"object","required":["id","type","function"],"properties":{"id":{"type":"string","description":"工具调用 ID。回传结果的 `tool` 消息里作为 `tool_call_id` 带回。"},"type":{"type":"string","enum":["function"],"description":"工具调用类型，始终为 `function`。"},"function":{"type":"object","properties":{"name":{"type":"string","description":"要执行的函数名。"},"arguments":{"type":"string","description":"JSON 字符串形式的调用参数。执行前先解析并按你的 schema 校验。"}}}}},"ChatCompletionResponse":{"type":"object","properties":{"id":{"type":"string","description":"补全请求的唯一标识符"},"object":{"type":"string","enum":["chat.completion"],"description":"对象类型，始终为 `chat.completion`"},"created":{"type":"integer","description":"创建时间的 Unix 时间戳"},"model":{"type":"string","description":"实际使用的模型 ID"},"choices":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","description":"选项索引"},"message":{"$ref":"#/components/schemas/ChatMessage"},"finish_reason":{"type":"string","enum":["stop","length","content_filter","tool_calls","refusal"],"description":"停止原因。常见取值：`stop` 表示正常结束，`length` 表示达到 max_tokens，`content_filter` 表示被内容过滤，`tool_calls` 表示模型请求调用工具而非直接作答，`refusal` 表示模型明确拒答而终止（例如 Claude 系列模型以 stop_reason refusal 结束）——此时 `message.refusal` 可能带拒答正文、`content` 可能为空。个别模型系列的原生终止原因也可能原样透传。"}}}},"usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer","description":"输入消耗的 token 数"},"completion_tokens":{"type":"integer","description":"输出消耗的 token 数"},"total_tokens":{"type":"integer","description":"总消耗的 token 数"}}}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"错误信息"},"type":{"type":"string","description":"错误类型"},"code":{"type":"string","description":"机器可读错误码（大写下划线），见文档开头错误码表"},"request_id":{"type":"string","description":"网关请求 ID，报障时请附上"}}}}},"AnthropicErrorResponse":{"type":"object","description":"/v1/messages 的错误外层结构——Anthropic Messages 形状，不是 OpenAI 的 {error} 形状","properties":{"type":{"type":"string","description":"固定为 \"error\""},"error":{"type":"object","properties":{"type":{"type":"string","description":"错误类型（authentication_error、billing_error、rate_limit_error、invalid_request_error、api_error、service_unavailable）"},"message":{"type":"string","description":"错误信息"},"code":{"type":"string","description":"机器可读错误码（大写下划线），部分计费错误不带"}}},"request_id":{"type":"string","description":"网关请求 ID（顶层字段，与 Anthropic 官方一致）；401、限流 429 等网关层错误带此字段"}}},"ImageGenerationRequest":{"type":"object","required":["model","prompt"],"properties":{"model":{"type":"string","description":"模型 ID。需选择支持图片生成能力的模型，可在[模型广场](https://router.one/zh/models)查询。","example":"gpt-image-2"},"prompt":{"type":"string","description":"图片生成的文本提示词。描述越具体、越富画面感，生成效果通常越好。建议长度不超过 4000 字符。","maxLength":4000},"n":{"type":"integer","description":"本次请求生成的图片数量。按张数计费。","minimum":1,"maximum":10,"default":1},"size":{"type":"string","description":"图片尺寸，格式 `宽x高`（像素），例如 `1024x1024`。按原值传给模型——Router One 不做校验，各模型支持的尺寸不同，部分模型会忽略该字段。模型拒绝的尺寸会返回 400 `invalid request (upstream rejected with status 400)`。支持的尺寸以该模型的目录页为准。","example":"1024x1024"},"quality":{"type":"string","description":"质量提示，按原值传给模型。Router One 不做校验；各模型接受的取值（若有）不同，没有质量控制项的模型会忽略它。模型拒绝的取值会返回 400 `invalid request (upstream rejected with status 400)`。计费按张、以该模型目录页的单价为准。Grok Imagine 的高画质档是独立模型 `grok-imagine-image-quality`，不是 quality 取值。"},"response_format":{"type":"string","enum":["url","b64_json"],"description":"响应中图片的返回方式。\n- `url`（默认）：返回 CDN URL，有效期约 1 小时，需自行下载或转存\n- `b64_json`：直接在响应中返回 base64 编码的图片字节，响应体较大但无需额外下载","default":"url"}}},"ImageEditRequest":{"type":"object","required":["model","prompt","image"],"properties":{"model":{"type":"string","description":"模型 ID。需选择支持图生图能力的模型，可在[模型广场](https://router.one/zh/models)查询。","example":"gemini-3.1-flash-image-preview"},"prompt":{"type":"string","description":"描述如何改写参考图的文本指令，例如「把这张照片变成水彩画风格」「把背景换成日落海滩」。建议长度不超过 4000 字符。","maxLength":4000},"image":{"type":"string","format":"binary","description":"参考图文件（PNG / JPEG / WebP 等）。所选模型支持多参考图时，可重复传多个 `image` 字段（也接受 `image[]`）。单个文件不超过 25 MB。"},"n":{"type":"integer","description":"本次请求生成的图片数量。按张数计费。","minimum":1,"maximum":10,"default":1},"size":{"type":"string","description":"输出图片尺寸，格式 `宽x高`（像素），例如 `1024x1024`。按原值传给模型——Router One 不做校验，各模型支持的尺寸不同，部分模型会忽略该字段。模型拒绝的尺寸会返回 400 `invalid request (upstream rejected with status 400)`。支持的尺寸以该模型的目录页为准。","example":"1024x1024"},"quality":{"type":"string","description":"质量提示，按原值传给模型。Router One 不做校验；各模型接受的取值（若有）不同，没有质量控制项的模型会忽略它。模型拒绝的取值会返回 400 `invalid request (upstream rejected with status 400)`。计费按张、以该模型目录页的单价为准。Grok Imagine 的高画质档是独立模型 `grok-imagine-image-quality`，不是 quality 取值。"},"response_format":{"type":"string","enum":["url","b64_json"],"description":"响应中图片的返回方式。\n- `url`（默认）：返回 CDN URL，有效期约 1 小时，需自行下载或转存\n- `b64_json`：直接在响应中返回 base64 编码的图片字节，响应体较大但无需额外下载","default":"url"}}},"ImageGenerationResponse":{"type":"object","properties":{"created":{"type":"integer","description":"生成完成时间的 Unix 时间戳（秒）"},"data":{"type":"array","description":"生成的图片列表，长度等于实际生成张数。","items":{"$ref":"#/components/schemas/ImageData"}}}},"ImageData":{"type":"object","properties":{"url":{"type":"string","nullable":true,"description":"图片 URL。仅当 `response_format=url` 时返回。"},"b64_json":{"type":"string","nullable":true,"description":"Base64 编码的图片字节。仅当 `response_format=b64_json` 时返回。"},"revised_prompt":{"type":"string","nullable":true,"description":"模型对原始 prompt 改写后的版本（部分模型会自动优化提示词）。可为空。"}}},"VideoGenerationRequest":{"type":"object","required":["model","prompt"],"properties":{"model":{"type":"string","description":"模型 ID。需选择支持视频生成能力的模型，可在[模型广场](https://router.one/zh/models)查询。","example":"<video-model-id-from-/models>"},"prompt":{"type":"string","description":"视频生成的文本提示词，描述画面内容、镜头运动、风格等。"},"duration":{"type":"integer","description":"2026-09-05 之前上架的视频模型都会忽略该字段：每个模型只出一种固定时长（见视频生成页的规格表）；截至 2026-10-01 目录没有视频模型。字段保留用于向前兼容。"},"size":{"type":"string","description":"2026-09-05 之前上架的视频模型都会忽略该字段（分辨率按模型固定、按条计价）；截至 2026-10-01 目录没有视频模型。字段保留用于向前兼容。","example":"720p"},"aspect_ratio":{"type":"string","enum":["16:9","9:16","1:1"],"description":"视频宽高比。`16:9` 适合横屏，`9:16` 适合竖屏短视频，`1:1` 适合社交方图。是否生效由具体视频模型决定；当前目录没有视频模型，使用前请核对模型页。"},"negative_prompt":{"type":"string","description":"反向提示词，描述希望避免出现的元素。可选；2026-09-05 之前上架的视频模型都不使用该字段，截至 2026-10-01 目录没有视频模型。"},"image_url":{"type":"string","format":"uri","description":"参考图 URL。图生视频模型必填（且只能一张）；文生视频模型带图会返回 400 `<model> is text-to-video only: image_url is not supported`。必须为 HTTP(S) 可访问地址，单图不超过 20MB。Router One 会代为下载并安全转存。"},"image_urls":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":3,"description":"多参考图 URL 列表。当前目录中没有模型接受多于一张参考图——传多张会返回 400 `<model> accepts exactly one image_url`。字段保留用于向前兼容；每张约束同 `image_url`。"},"input_reference":{"type":"string","description":"模型特定的参考输入标识。仅当所选模型明确要求时使用；它会被当作参考图处理，因此与 `image_url` 遵守同样的模型规则。"}}},"VideoSubmitResponse":{"type":"object","required":["task_id","status"],"properties":{"task_id":{"type":"string","description":"任务标识，作为不透明字符串使用。后续查询接口需原样回传，**请勿尝试解析其内部结构**。"},"status":{"type":"string","enum":["pending"],"description":"提交后的初始状态，始终为 `pending`。"}}},"VideoStatusResponse":{"type":"object","required":["task_id","status"],"properties":{"task_id":{"type":"string","description":"任务标识，与提交时返回的 `task_id` 一致。"},"status":{"type":"string","enum":["pending","processing","completed","failed"],"description":"任务状态。\n- `pending`：已接受，未开始处理\n- `processing`：生成中（当前目录中的模型不返回 `progress`）\n- `completed`：已完成，读取 `url` 获取视频\n- `failed`：失败，读取 `error` 获取原因"},"url":{"type":"string","nullable":true,"description":"生成的视频 URL。仅当 `status=completed` 时返回。URL 有效期通常为 24 小时，请及时下载或转存。"},"error":{"type":"string","nullable":true,"description":"失败原因的人类可读描述。仅当 `status=failed` 时返回。"},"progress":{"type":"integer","nullable":true,"minimum":0,"maximum":100,"description":"生成进度百分比（0-100），部分模型可能不返回。"}}},"MessageRequest":{"type":"object","required":["model","messages","max_tokens"],"properties":{"model":{"type":"string","description":"模型 ID。设为 `auto` 时由 Router One 自动选择，也可以指定具体模型。大多数不带厂商前缀的官方模型名（如 `gpt-5.5`、`claude-sonnet-5`）可作为目录 ID 的别名使用；稳妥起见请从 /models 复制目录 ID。","example":"auto"},"messages":{"type":"array","description":"Claude / Anthropic Messages 格式的对话消息。","items":{"$ref":"#/components/schemas/AnthropicMessage"},"minItems":1},"system":{"type":"string","description":"可选系统提示词。"},"max_tokens":{"type":"integer","description":"最大输出 token 数。","minimum":1},"stream":{"type":"boolean","description":"是否启用流式响应。","default":false},"temperature":{"type":"number","description":"采样温度，范围 0-2。","minimum":0,"maximum":2,"default":1},"tools":{"type":"array","description":"Anthropic 工具声明，按原样转发。function 工具带 `input_schema`；服务端工具 `web_search` 与 `code_execution` 被接受，`web_fetch` 与 `mcp_toolset` 会被拒绝并返回 400 invalid_request_error。","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"工具名称。"},"description":{"type":"string","description":"工具用途说明——模型据此决定何时调用。"},"input_schema":{"type":"object","description":"工具入参的 JSON Schema（function 工具）。"}}}},"tool_choice":{"type":"object","description":"模型如何使用已声明的工具（`auto`、`any`、`tool`、`none`），按原样转发——Claude Opus 5.5（`claude-opus-5-5` 或 `anthropic/claude-opus-5.5`）除外：对这个模型 `any` 与 `tool` 会按 `auto` 发送，所以要检查 `stop_reason` 和内容块类型；模型是否接受强制选择由厂商决定。"}}},"AnthropicMessage":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["user","assistant"],"description":"消息角色。"},"content":{"oneOf":[{"type":"string","description":"纯文本内容。"},{"type":"array","description":"内容块列表。","items":{"$ref":"#/components/schemas/AnthropicContentBlock"}}]}}},"AnthropicContentBlock":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["text","image","tool_use","tool_result"],"description":"内容块类型。`tool_use` / `tool_result` 块按原样往返。"},"text":{"type":"string","description":"文本内容，`type=text` 时使用。"},"source":{"type":"object","description":"图片来源，`type=image` 时使用。","properties":{"type":{"type":"string","example":"url"},"url":{"type":"string","example":"https://example.com/image.png"}}},"id":{"type":"string","description":"工具调用 ID，`type=tool_use` 时使用。"},"name":{"type":"string","description":"工具名称，`type=tool_use` 时使用。"},"input":{"type":"object","description":"工具入参，`type=tool_use` 时使用。"},"tool_use_id":{"type":"string","description":"本结果对应的 `tool_use` 块 ID，`type=tool_result` 时使用。"},"content":{"description":"工具结果，`type=tool_result` 时使用——字符串或内容块列表。","oneOf":[{"type":"string"},{"type":"array","items":{"type":"object"}}]}}},"MessageResponse":{"type":"object","properties":{"id":{"type":"string","description":"消息 ID。"},"type":{"type":"string","enum":["message"],"description":"对象类型。"},"role":{"type":"string","enum":["assistant"],"description":"回复角色。"},"model":{"type":"string","description":"实际调用的模型 ID。"},"content":{"type":"array","items":{"$ref":"#/components/schemas/AnthropicContentBlock"}},"stop_reason":{"type":"string","description":"停止原因。"},"usage":{"type":"object","properties":{"input_tokens":{"type":"integer","description":"输入 token 数。"},"output_tokens":{"type":"integer","description":"输出 token 数。"}}}}},"ResponsesRequest":{"type":"object","required":["model","input"],"properties":{"model":{"type":"string","description":"模型 ID。设为 `auto` 时由 Router One 自动选择。大多数不带厂商前缀的官方模型名（如 `gpt-5.5`、`claude-sonnet-5`）可作为目录 ID 的别名使用；稳妥起见请从 /models 复制目录 ID。","example":"auto"},"input":{"oneOf":[{"type":"string","description":"输入文本。"},{"type":"array","description":"Responses API 输入项列表。带 file_id 或 file_url 的 input_file 块在原生走 Responses 线协议的模型上可用。","items":{"$ref":"#/components/schemas/ResponseInputItem"}}]},"instructions":{"type":"string","description":"可选系统指令。"},"stream":{"type":"boolean","description":"是否启用流式响应。","default":false},"temperature":{"type":"number","description":"采样温度，范围 0-2。","minimum":0,"maximum":2,"default":1},"max_output_tokens":{"type":"integer","description":"最大输出 token 数。","minimum":1},"tools":{"type":"array","description":"工具声明。function 工具是 Codex 的默认形态；custom 工具与 hosted 工具（file_search、code_interpreter、computer_use、mcp、web_search）在原生走 Responses 线协议的模型上可用，按该模型公示单价计费。image_generation 工具会返回 400 invalid_request——请改用 /v1/images/generations。","items":{"type":"object","description":"一条 Responses API 形态的工具声明（type 加该工具自身字段）。"}},"previous_response_id":{"type":"string","description":"从上一条 response 续接（服务端上下文引用）。仅在原生走 Responses 线协议的模型上可用；其他模型返回 400 invalid_request。"},"conversation":{"description":"会话引用（id 字符串或对象）。模型限制与 previous_response_id 相同。","oneOf":[{"type":"string","description":"会话 id。"},{"type":"object","description":"带 id 字段的会话对象。","properties":{"id":{"type":"string"}}}]},"prompt":{"type":"object","description":"Prompt 模板引用（id 加变量）。模型限制与 previous_response_id 相同。","properties":{"id":{"type":"string","description":"Prompt 模板 id。"},"variables":{"type":"object","description":"模板变量。"}}},"service_tier":{"type":"string","description":"可选的 OpenAI 处理档位字段。Router One 按模型公示单价计费（见[定价页](https://router.one/zh/pricing)），并可能对该字段做规范化处理。"},"store":{"type":"boolean","description":"按原样转发。"},"background":{"type":"boolean","description":"不支持——background: true 会返回 400 invalid_request。网关不提供后台执行，也没有 GET /v1/responses/{id}；请求必须在 HTTP 连接内完成。","default":false}}},"ResponseInputItem":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["system","developer","user","assistant"],"description":"输入项角色。`developer` 项（Codex CLI 默认形态）按原样透传。"},"content":{"oneOf":[{"type":"string","description":"纯文本内容。"},{"type":"array","description":"内容块列表。","items":{"$ref":"#/components/schemas/ResponseContentPart"}}]}}},"ResponseContentPart":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["input_text","output_text","input_image"],"description":"内容块类型。"},"text":{"type":"string","description":"文本内容。"},"image_url":{"type":"string","description":"图片 URL。"}}},"ResponsesResponse":{"type":"object","properties":{"id":{"type":"string","description":"响应 ID。"},"object":{"type":"string","enum":["response"],"description":"对象类型。"},"created_at":{"type":"integer","description":"创建时间戳。"},"status":{"type":"string","description":"响应状态。"},"model":{"type":"string","description":"实际调用的模型 ID。"},"output_text":{"type":"string","description":"聚合后的文本输出。"},"output":{"type":"array","description":"原始输出项。","items":{"$ref":"#/components/schemas/ResponseInputItem"}},"usage":{"type":"object","properties":{"input_tokens":{"type":"integer","description":"输入 token 数。"},"output_tokens":{"type":"integer","description":"输出 token 数。"},"total_tokens":{"type":"integer","description":"总 token 数。"}}}}}}},"x-ext-urls":{}}