API 参考/接口与请求示例/Responses

Responses

OpenAI Responses 兼容接口，Codex CLI 默认使用这个格式。输入用 input 字段，输出是 output 数组，推理和工具调用都是独立的条目。

POSThttps://api.wokey.ai/v1/responses· OpenAI Responses 兼容
本页内容expand_more

调用示例link

Base URL 写 https://api.wokey.ai/v1。Codex CLI 的配置方法见客户端接入里的 Codex CLI 一页。

curl https://api.wokey.ai/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-sol",
    "instructions": "You are a helpful assistant.",
    "input": [
      { "role": "user", "content": "Hello" }
    ],
    "reasoning": { "effort": "medium" },
    "store": false
  }'

请求头link

Header取值说明
Authorization必填Bearer YOUR_API_KEY你的 Wokey API Key。也可以改用 x-api-key: YOUR_API_KEY。
Content-Type必填application/json请求体是 JSON。
X-End-User-Idstring可选。你的终端用户 ID，1–128 个可见 ASCII 字符。传了之后，因反复违规触发的限制只作用于这个终端用户。

请求参数link

下表是网关读取或会改变行为的参数。其他参数按所选模型的上游支持情况转发。

参数类型说明
model必填string模型 ID，必须是非空字符串，并且和模型列表里的 ID 完全一致。
input必填string | array输入内容。可以是一段文本，也可以是消息和条目组成的数组。这个接口不接受 messages 字段，传了会返回 400。
instructionsstring系统指令。GPT 模型不传时，网关会补上 "You are a helpful assistant."。
reasoningobject如 {"effort": "high", "summary": "auto"}。GPT 不传时 effort 为 medium。Claude 模型从这个接口调用时不生效。
streamboolean为 true 时以 SSE 事件流返回。
toolsarray函数工具和 web_search 等内置工具。tool_choice、parallel_tool_calls 同样支持。
textobject输出格式，如用 text.format 声明 JSON Schema 结构化输出。
max_output_tokensintegerGPT 模型不支持，会被忽略。Claude 模型会映射成 max_tokens，不传时按 4096。Grok、DeepSeek、MiniMax 等模型原样转发。
storebooleanGPT 模型一律按 false 处理，Wokey 不在上游保存对话。
previous_response_idstring不支持。因为不在上游保存对话，每轮请求都要在 input 里带上完整历史，Codex CLI 默认就是这样做的。
includearray如 ["reasoning.encrypted_content"]，返回加密的推理内容。下一轮把这些 reasoning 条目原样放回 input，可以延续推理并命中缓存。
prompt_cache_keystring缓存键，最长 64 个字符。同一会话使用固定值，有助于命中缓存。
providerobjectWokey 扩展字段，用来指定或排除供应商，只用于路由，不会转发给上游。

Wokey 的处理link

网关在转发前后做的事，和直接调用官方接口不同的地方都写在这里。

  • GPT 模型直接按 Responses 格式转发，不做格式转换。主要调整：store 固定为 false；不转发 user、safety_identifier、max_output_tokens 和采样参数；input 里 role 为 system 的条目改为 developer。
  • Claude、DeepSeek 等非 OpenAI 模型也能用这个格式调用。Claude 从这里调用时不支持推理设置，usage 只有 input_tokens、output_tokens、total_tokens；要使用 Claude 的完整能力请用 Messages 接口。
  • POST /v1/responses/input_tokens 统计一次请求的输入 token 数。POST /v1/responses/compact 压缩上下文，只支持 GPT 模型。
  • GET /v1/responses（WebSocket 模式）不支持，返回 426 websocket_not_supported。
  • metadata 和 provider 不会转发给上游。

同一个模型有多家供应商时，可以在请求体里加 provider 指定或排除供应商。 指定供应商与顺序 →

响应link

JSON
{
  "id": "resp_...",
  "object": "response",
  "status": "completed",
  "model": "gpt-6-sol",
  "output": [
    { "type": "reasoning", "id": "rs_...", "summary": [] },
    {
      "type": "message",
      "id": "msg_...",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "Hello! How can I help you today?" }]
    }
  ],
  "usage": {
    "input_tokens": 21,
    "input_tokens_details": { "cached_tokens": 0 },
    "output_tokens": 42,
    "output_tokens_details": { "reasoning_tokens": 32 },
    "total_tokens": 63
  }
}
  • 响应头 x-wokey-request-id 是这次请求在 Wokey 的 ID，排查问题时提供它。
  • output 数组按顺序列出推理、消息和工具调用条目。SDK 的 output_text 会把所有文本拼在一起。
  • GPT 模型：input_tokens 包含命中缓存的部分，命中的数量在 input_tokens_details.cached_tokens 里；推理 token 在 output_tokens_details.reasoning_tokens 里。
  • Claude 模型：input_tokens 不含缓存，也不返回缓存明细。

流式返回link

每个事件有 event: 行和 data: 行，最后一个事件是 response.completed。

SSE
event: response.created
data: {"type":"response.created","response":{"id":"resp_...","status":"in_progress"}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_...","output_index":1,"delta":"Hello!"}

event: response.output_text.done
data: {"type":"response.output_text.done","item_id":"msg_...","output_index":1,"text":"Hello! How can I help you today?"}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_...","status":"completed","usage":{"input_tokens":21,"output_tokens":42,"total_tokens":63}}}
  • GPT 模型原样转发上游的事件流。
  • 其他模型的事件由网关按 Responses 格式生成，以 response.completed 结束，随后发送 data: [DONE]。
  • 流中出错时发送 response.failed 事件。
  • 等待上游首个字节时，网关会定期发送 SSE 注释行保持连接，客户端会自动忽略。

错误格式link

JSON
{
  "error": {
    "code": "model_not_found",
    "message": "Model ID \"gpt-6-sun\" was not recognized. The correct model ID is \"gpt-6-sol\"; use it and try again. See https://wokey.ai/models for the full list.",
    "type": "invalid_request_error"
  }
}

错误使用 OpenAI 格式：error.code 是可以用来判断的错误码，error.type 一般是 invalid_request_error。各状态码的含义和处理方法见 错误码与排障 →