> ## Documentation Index > Fetch the complete documentation index at: https://docs.bytespike.ai/llms.txt > Use this file to discover all available pages before exploring further. # POST /responses > ByteSpike 上的 OpenAI Responses API —— 用 o-series 和 GPT-5 的结构化输出形状去打目录里任意模型。 Responses API 形状（OpenAI 为 o1 / o3 / GPT-5 + Agents SDK 引入）—— 由 ByteSpike 像其他端点一样计费和服务。底下网关把 Responses 形状的请求翻译 成各模型的原生协议，所以你可以把 OpenAI SDK + Agents SDK + Codex CLI 指向 ByteSpike，让它跑在 Claude、Gemini、DeepSeek 等模型上。 ## 何时使用 * **OpenAI Agents SDK** —— SDK 默认讲 Responses 形状 * **Codex CLI** —— 内部用 Responses；ByteSpike 通过 `--responses-base-url https://llm.bytespike.ai/v1` 直接接入 * **多轮 agent + 结构化输出** —— `response_format` 加 reasoning 块装在同一个信封里 * **跨模型一致** —— 你想要一种客户端形状打通 o-series、GPT-5 和 Claude 家族 只是普通聊天、不需要 reasoning 步骤的话，优先用 [`/chat/completions`](./openai-chat-completions)。要 Anthropic 原生的 tool\_use + cache\_control，用 [`/messages`](./claude-messages)。 ## 请求 ```bash theme={null} curl https://llm.bytespike.ai/v1/responses \ -H "Authorization: Bearer $BYTESPIKE_API_KEY" \ -H "content-type: application/json" \ -d '{ "model": "gpt-5-5", "input": "What is the capital of France?" }' ``` ### 请求头 | Header | 是否必填 | 说明 | | --------------- | ---- | ------------------------------------------ | | `Authorization` | 是 | `Bearer sk-byts-…` —— Responses 唯一接受的鉴权形式。 | | `content-type` | 是 | `application/json`。 | ### Body（精选字段） Responses API 字段众多；ByteSpike 把完整 schema 转发给你请求的 `model`。常用字段： | 字段 | 类型 | 是否必填 | 说明 | | ---------------------- | ---------------- | ---- | -------------------------------------------------------------------------------------- | | `model` | string | 是 | 目录 slug（`gpt-5-5`、`claude-opus-4-8`、`gpt-5-4-mini` 等）。 | | `input` | string \| array | 是 | 对话内容。string = 单条 user 消息；array = 多轮（role/content 形状按 OpenAI Responses spec）。 | | `instructions` | string | 否 | 相当于 system prompt 位。 | | `tools` | array | 否 | Responses 形状的工具定义（`{type, name, parameters, …}`）。 | | `tool_choice` | string \| object | 否 | `auto` / `none` / `required` / `{type: "function", function: {name}}`。 | | `temperature` | number | 否 | 默认 `1.0`。 | | `top_p` | number | 否 | Nucleus sampling。 | | `max_output_tokens` | integer | 否 | 输出 token 上限。 | | `reasoning` | object | 否 | `{"effort": "low" \| "medium" \| "high"}` —— 用于 o-series 和 GPT-5 reasoning 模型。 | | `response_format` | object | 否 | `{"type": "json_object"}` 或 `{"type": "json_schema", "json_schema": {...}}`，用于严格结构化输出。 | | `stream` | boolean | 否 | SSE 推流。与 OpenAI Responses 规范相同的事件协议。 | | `metadata` | object | 否 | `{"user_id": "..."}` —— 转发给模型 + 记录。 | | `previous_response_id` | string | 否 | 多轮串联；引用前一个 `response.id`。 | ## 响应 ```json theme={null} { "id": "resp_01HQX9F2P6Y8VEX3CRZ8GXJVD9", "object": "response", "created_at": 1716700000, "model": "gpt-5-5", "status": "completed", "output": [ { "type": "message", "id": "msg_01ABC", "role": "assistant", "content": [ {"type": "output_text", "text": "Paris."} ] } ], "usage": { "input_tokens": 9, "output_tokens": 2, "total_tokens": 11 } } ``` ### 响应字段 | 字段 | 类型 | 说明 | | ------------------------ | ------- | -------------------------------------------------------- | | `id` | string | 服务端生成的 id，前缀 `resp_`。用于 `previous_response_id` 串联。 | | `status` | string | `completed`、`in_progress`、`failed`。非流式成功恒为 `completed`。 | | `output` | array | 输出项数组。每项有 `type` —— `message`、`reasoning`、`tool_call` 等。 | | `usage.input_tokens` | integer | 输入计费 token 数。 | | `usage.output_tokens` | integer | 输出计费 token 数（o-series 包含 reasoning token）。 | | `usage.reasoning_tokens` | integer | 应用时为隐藏 reasoning 使用的 `output_tokens` 子集。 | ### 计费类请求头 与其他端点一致的配额信封： ``` X-RateLimit-Limit: 50.00 X-RateLimit-Remaining: 42.18 X-RateLimit-Reset: 1716705600 X-Quota-Remaining-Credits: 192.40 ``` 详见 [API 参考总览](/zh/api-reference/overview#conventions)。 ## 流式 带上 `"stream": true`： ```bash theme={null} curl -N https://llm.bytespike.ai/v1/responses \ -H "Authorization: Bearer $BYTESPIKE_API_KEY" \ -H "content-type: application/json" \ -d '{ "model": "gpt-5-5", "input": "Tell a 3-sentence story.", "stream": true }' ``` SSE 流逐字节兼容 OpenAI Responses 的流式协议 —— `response.created`、 `response.output_text.delta`、`response.completed` 等。 ## 跨模型路由 同一种 Responses 请求形状可打目录里每个模型。按 `model` 字段选择： | 模型家族 | 示例 slug | 说明 | | ---------------- | -------------------------------------------------------- | -------------------------------------- | | GPT-5 / o-series | `gpt-5-5`、`gpt-5-4`、`gpt-5-4-mini` | 原生 Responses 形状 —— 无需翻译。 | | Claude | `claude-opus-4-8`、`claude-sonnet-4-6`、`claude-haiku-4-5` | `reasoning` 映射到 Claude 的 `thinking` 块。 | | Gemini | `gemini-3-5-flash` | 完整支持 Responses 表面。 | 翻译路径保留 `tool_use` / `tool_calls`、结构化输出（`response_format`）和 reasoning tokens。不论用哪个模型，你拿到的输出形状始终是 Responses-API。 ## 错误 OpenAI 信封（与 OpenAI Responses 规范一致）： ```json theme={null} { "error": { "message": "Model \"foo-3\" not found", "type": "invalid_request_error", "code": "model_not_found" } } ``` | HTTP | `code` | 触发 | | --------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | 400 | `invalid_request_error` | JSON 错误、缺 `model`、`tools` 不合法。 | | 401 | `authentication_error` | key 缺失 / 已撤销。 | | 402 | `insufficient_balance` | 账户 credits 用尽。在 [console.bytespike.ai](https://console.bytespike.ai) 充值。 | | 413 | `invalid_request_error`（body too large） | prompt + 工具 schema 超过 body 上限。 | | 429 | `rate_limit_exceeded` | 见速率限制章节。 | | 502 / 503 | `api_error` | 瞬时超时或路由分组中暂无可用容量来服务该 `model`。[Console → Models](https://console.bytespike.ai/dosia/models) 中的 dial-test 可帮助排查。 | ## 价格 按 1k token 计费。与该模型在原生端点的价格相同 —— 翻译开销不计费。 价格实时卡片：[bytespike.ai/pricing](https://bytespike.ai/pricing)。 ## 相关 * [`/chat/completions`](./openai-chat-completions) —— OpenAI Chat Completions 形状 * [`/messages`](./claude-messages) —— Anthropic Messages 形状 * [使用 ByteSpike 配置 Codex](/zh/configure-client) —— 具体的 CLI 配置