API 参考/接口与请求示例/Chat Completions

Chat Completions

OpenAI Chat Completions 兼容接口。OpenAI SDK、大多数聊天客户端和 Agent 框架都能直接接入，Claude、Gemini、DeepSeek 等非 OpenAI 模型也可以用这个格式调用。

POSThttps://api.wokey.ai/v1/chat/completions· OpenAI Chat Completions 兼容
本页内容expand_more

调用示例link

Base URL 写 https://api.wokey.ai/v1，OpenAI SDK 不需要其他改动。不带 /v1 的 /chat/completions 也能用。

curl https://api.wokey.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-sol",
    "messages": [
      { "role": "system", "content": "You are a helpful assistant." },
      { "role": "user", "content": "Hello" }
    ],
    "max_tokens": 1024
  }'

请求头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

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

参数类型说明
model必填string模型 ID，必须和模型列表里的 ID 完全一致。ID 写错返回 404 model_not_found，错误信息里会给出最接近的正确 ID。
messages必填array对话消息，至少一条。role 取 system、developer、user、assistant 或 tool；content 可以是字符串，也可以是 text、image_url 内容块组成的数组。
max_tokensinteger输出 token 上限，必须是正整数，也接受 max_completion_tokens。Claude 模型不传时按 4096；GPT 模型由上游决定，会忽略这个值。
streamboolean为 true 时以 SSE 流式返回，见下方「流式返回」。
toolsarray函数工具定义。所有模型都用同一种写法，网关会转换成上游需要的格式。tool_choice、parallel_tool_calls 同样支持。
reasoning_effortstringGPT 等推理模型的思考强度，如 low、medium、high；GPT 不传时为 medium。Claude 模型从这个接口调用时不生效，按模型默认强度思考；要控制 Claude 的思考请用 Messages 接口。
response_formatobject结构化输出。只对按 Chat 格式原样转发的模型生效，如 DeepSeek、GLM、Kimi；GPT 和 Claude 模型会忽略它，需要结构化输出请改用 Responses 的 text.format 或 Messages 接口。
stopstring | array停止序列。Claude 模型会转成 stop_sequences；GPT 模型不支持，会被忽略。
temperaturenumber当前的推理模型自己决定采样参数，网关不转发 temperature。只有 Claude Opus 4.6、Sonnet 4.6、Sonnet 4.5、Haiku 4.5（范围 0–1）和 Grok 接受它。top_p 同理。
prompt_cache_keystringGPT 模型的缓存键，最长 64 个字符。不传时网关按对话开头自动生成，同一对话的多轮请求仍能命中缓存。
cache_controlobject只对 Claude 模型生效，写在请求体顶层。网关默认为 Claude 请求开启 5 分钟提示缓存；传 {"type": "ephemeral", "ttl": "1h"} 可改成 1 小时缓存，1 小时缓存的写入价更高。
providerobjectWokey 扩展字段，用来指定或排除供应商，只用于路由，不会转发给上游。

Wokey 的处理link

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

  • 所有文本模型都能用这个格式调用。网关按模型选择上游协议，自动转换请求和响应，调 Claude、Gemini 不用换 SDK。
  • 生图和视频模型不能从这里调用，会返回 404，错误信息会指向 /v1/images/generations 或 /v1/videos。
  • 图片输入用 image_url，支持 https 链接和 base64 data URL。模型不支持图片时返回 400 model_does_not_support_images。
  • PDF 等文件输入只对按 Chat 格式原样转发的模型生效。要给 Claude 传 PDF，请用 Messages 接口的 document 内容块。
  • metadata 和 provider 不会转发给上游。

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

响应link

JSON
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1793952000,
  "model": "gpt-6-sol",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello! How can I help you today?" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 21,
    "completion_tokens": 10,
    "total_tokens": 31
  }
}
  • 响应头 x-wokey-request-id 是这次请求在 Wokey 的 ID。排查问题时请提供它。
  • Claude 模型：prompt_tokens 不含缓存，缓存读写在 cache_read_input_tokens 和 cache_creation_input_tokens 里单独列出。
  • GPT 模型：prompt_tokens 包含命中缓存的部分，命中的数量在 input_tokens_details.cached_tokens 里。
  • 其他模型：返回上游原本的 usage，缓存命中通常在 prompt_tokens_details.cached_tokens 里。
  • 非流式请求超过约 2 分钟还没完成时，网关会先返回 200 状态码，并持续发送空白字符保持连接。此后如果出错，错误对象会出现在这个 200 响应的响应体里。长任务建议用 stream: true。

流式返回link

每个事件是一行 data: 加一个 chunk JSON，最后以 data: [DONE] 结束。

SSE
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","model":"gpt-6-sol","choices":[{"index":0,"delta":{"content":"Hello!"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","model":"gpt-6-sol","choices":[{"index":0,"delta":{"content":" How can I help you today?"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","model":"gpt-6-sol","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":21,"completion_tokens":10,"total_tokens":31}}

data: [DONE]
  • 最后一个 chunk 同时带 finish_reason 和 usage。不用设置 stream_options.include_usage，网关总会返回 usage。
  • 工具调用不是逐字流出的：完整的 tool_calls 在流的末尾一次给出。
  • Claude 模型和按 Chat 格式原样转发的推理模型，会在 delta.reasoning_content 里流式输出思考内容。GPT 模型不返回思考文本。
  • 等待上游首个字节时，网关会定期发送 : keepalive 注释行，SSE 客户端会自动忽略。
  • 流已经开始后出错时，网关发送一个 data: {"error": …} 事件，再发送 data: [DONE]。

错误格式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。各状态码的含义和处理方法见 错误码与排障 →