对话
聊天补全
所有文本模型均可通过 OpenAI 的 Chat Completions API 调用:请求与响应格式、流式输出和 SDK 都保持一致。
/v1/chat/completions请求
modelstring必填- 模型页面中的模型 ID,例如
claude-opus-5-5或gpt-6-sol。 messagesarray必填- 对话内容:
system(或developer)、user、assistant和tool消息。content可以是字符串,也可以是内容片段数组,用于添加图片、PDF、音频或视频。 streamboolean- 通过服务器发送事件 (SSE),边生成边返回答案。详见下文的流式输出。
stream_optionsobject{ "include_usage": true }会在末尾追加一个包含 token 用量的数据块。max_completion_tokensinteger- 生成的 token 数量上限,包含推理 token。也支持
max_tokens。 temperaturenumber- 0 到 2。越低越集中,越高越多样。部分推理模型会忽略此参数。Claude 从 Opus 4.7 起的模型 (Opus 5 和 5.5、Fable 5 和 5.1、Sonnet 5.5、Haiku 5.5) 不接受此参数,因此我们不会向这些模型传递它。
top_pnumber- 核采样,范围为 0 到 1。此参数与 temperature 只需调整一个,不要同时调整。上述 Claude 模型不传递此参数;这些模型和 Muse Wonder 也不传递 top_k。
stopstring | array- 最多 4 个停止序列,遇到任意一个即停止生成。
toolsarray- 模型可以调用的函数。详见下文的工具调用。
tool_choicestring | objectauto、none、required,或指定函数。如果模型厂商拒绝或忽略某个选项 (Claude Opus 5.5、Sonnet 5.5 和 Fable 5.1 的强制工具调用;Muse Wonder 除auto以外的选项;部分 Gemini、DeepSeek Flash、MiMo、HY4 和 MiniMax 模型的none),我们会转换为模型能遵循的形式,并向模型说明你的要求;如果按名称强制调用某个函数,就只向模型提供该函数。response_formatobject- JSON 输出:
{ "type": "json_object" },或附带 schema 的json_schema。详见下文的结构化输出。 reasoning_effortstring- 推理模型的思考强度:
none、minimal、low、medium、high、xhigh或max。每个模型只支持其中部分级别 (详见下文的推理);传入其他级别时,会按最接近的受支持级别运行。级别越高,思考时间越长,消耗的输出 token 越多。 seedinteger- 对支持的模型,尽可能保证结果可复现。
modelsarray- 本次请求的智能路由配置:模型不可用时,按顺序尝试的备选模型。参见智能路由。
user 和 metadata 除外,它们由我们处理。模型支持哪些参数 (工具、JSON schema、推理) 取决于模型本身,与直接调用其所属厂商的 API 时相同。使用 OpenAI Python SDK 时,请通过 extra_body={"models": [...]} 传入 models。响应
{ "id": "chatcmpl-AbC123...", "object": "chat.completion", "created": 1790870400, "model": "claude-opus-5-5", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Here's the summary..." }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 1204, "completion_tokens": 312, "total_tokens": 1516, "prompt_tokens_details": { "cached_tokens": 1024 }, "completion_tokens_details": { "reasoning_tokens": 128 } }}model是实际响应的模型。通常就是你请求的模型,除非智能路由改用了备选模型。- 推理模型可能会在消息中添加
reasoning_content: 即模型愿意公开的思考内容。 usage是计费依据。cached_tokens是从模型的提示词缓存中读取的输入 token, 如果该模型提供缓存价格,则按缓存价格计费。
每个响应还包含以下响应头:
流式传输
设置 stream: true 后,回答会以服务端发送事件 (SSE) 的形式返回,使用 OpenAI 的分块格式,以 data: [DONE] 结束。各 SDK 都会自动解析这些事件。
import osfrom openai import OpenAIclient = OpenAI( base_url="https://api.zurelay.com/v1", api_key=os.environ["ZURELAY_API_KEY"],)stream = client.chat.completions.create( model="claude-sonnet-5-5", messages=[ { "role": "user", "content": "Write a limerick about databases." } ], stream=True, stream_options={ "include_usage": True },)for chunk in stream: if chunk.choices and chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end="", flush=True)- 模型生成首个 token 后才开始发送回答,因此重试或切换到其他通道的过程对你不可见。
- 静默期间 (模型在步骤间思考时),每隔 15 秒会发送一行 SSE 注释 (
: keep-alive)。客户端会忽略它们,但这些注释能防止代理关闭连接。如果首个 token 的等待时间超过 20 秒 (例如提示词较长,或某条通道停滞、正在切换),此时就会开启流:等待期间会收到响应头和保活注释。每条通道最多等待 3 分钟开始生成 (高推理强度时为 5 分钟),超时后尝试下一条,因此请将客户端超时设为 10 分钟。 - 在首个 token 生成前开启的流,仅在其他模型无法接替响应时 (智能路由关闭) 才携带
x-zurelay-model。流开启后发生的错误会以流内错误事件返回 (结构与错误响应体相同),而非错误状态码。 - 设置
include_usage后,[DONE]前的最后一个分块包含一个空的choices列表和usage。
工具调用
在 tools 中描述函数;模型需要调用函数时,会返回 tool_calls 而非文本。执行函数后,将结果作为 tool 消息发回,并附上该次调用的 ID, 模型就会继续生成。
import osfrom openai import OpenAIclient = OpenAI( base_url="https://api.zurelay.com/v1", api_key=os.environ["ZURELAY_API_KEY"],)response = client.chat.completions.create( model="gpt-6-sol", messages=[ { "role": "user", "content": "What's the weather in Lisbon right now?" } ], tools=[ { "type": "function", "function": { "name": "get_weather", "description": "Current weather for a city", "parameters": { "type": "object", "properties": { "city": { "type": "string" } }, "required": [ "city" ] } } } ],)print(response.choices[0].message.content)结构化输出
通过 response_format 请求 JSON 输出。对于支持的模型,json_schema 会约束输出遵循你的 schema; json_object 则只要求输出有效的 JSON (也请在提示词中明确要求)。
import osfrom openai import OpenAIclient = OpenAI( base_url="https://api.zurelay.com/v1", api_key=os.environ["ZURELAY_API_KEY"],)response = client.chat.completions.create( model="gpt-6.1-sol", messages=[ { "role": "user", "content": "Extract the people: 'Ana met Ben and Chloe in Porto.'" } ], response_format={ "type": "json_schema", "json_schema": { "name": "people", "schema": { "type": "object", "properties": { "names": { "type": "array", "items": { "type": "string" } } }, "required": [ "names" ] } } },)print(response.choices[0].message.content)推理
推理模型会先思考再回答。通过 reasoning_effort 在速度、成本和思考深度之间取舍:级别越高,思考越久、耗时越长,消耗的输出 token 也越多。各模型支持其所属厂商文档中列出的级别,从 none (不思考),经 minimal、low、medium、high 和 xhigh (超高),到 max; 具体见下表。不传此参数则使用模型的默认级别。所有 OpenAI SDK 的用法都相同,你也可以在控制台的调试台中试用各个级别。
from openai import OpenAIclient = OpenAI(base_url="https://api.zurelay.com/v1", api_key="YOUR_ZURELAY_KEY")response = client.chat.completions.create( model="zurelay-auto", reasoning_effort="high", messages=[{"role": "user", "content": "How many primes are there below 1,000?"}],)message = response.choices[0].messageprint(getattr(message, "reasoning_content", None)) # the thinking, when the model shares itprint(message.content)对于公开思考内容的模型,思考内容会随回答一起通过 message.reasoning_content 返回 (流式响应中通过 delta.reasoning_content); 少数模型将该字段命名为 reasoning。思考内容按输出 token 计费,且始终计入 completion_tokens; 如果模型提供相应统计,completion_tokens_details.reasoning_tokens 会单独记录其数量。高推理强度下,回答可能需要数分钟才开始生成,因此请为客户端设置足够长的超时时间 (参见可靠性与超时)。
各模型的推理级别
以下信息来自各厂商的官方文档。如果指定的级别不受支持,会使用最接近的受支持级别 (若有两个同样接近的级别,则取较低者;只有传入 none 才会关闭思考),因此同一请求可用于所有模型,包括智能路由场景。x-zurelay-reasoning-effort 响应头会标明实际使用的级别。如果传入的词不属于任何推理级别,请求会被拒绝,并返回 400, 其中列出该模型支持的级别。
Claude 的思考
通过此端点调用时,Claude 与其他模型一样支持 reasoning_effort: 可设为 low、medium、high、xhigh 或 max (Opus 4.6 不支持 xhigh)。使用 Anthropic 原生格式时,Claude 会按指定级别自适应思考:发送 thinking: { type: "adaptive", display: "summarized" } 并设置 output_config: { effort: "xhigh" }, 然后读取思考内容块。参见 Anthropic Messages。
有疑问,或发现内容缺失?联系我们的支持团队,我们会通过邮件回复,通常只需一分钟。