对话

聊天补全

所有文本模型均可通过 OpenAI 的 Chat Completions API 调用:请求与响应格式、流式输出和 SDK 都保持一致。

POST/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 | object
auto、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
本次请求的智能路由配置:模型不可用时,按顺序尝试的备选模型。参见智能路由。
其他 OpenAI 参数会原样传给模型,但 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, 如果该模型提供缓存价格,则按缓存价格计费。

每个响应还包含以下响应头:

请求头值
x-request-id请求 ID, 与请求日志中的一致。联系支持时请提供此 ID。
x-zurelay-model实际响应的模型。
x-zurelay-routed-from仅在使用智能路由后返回:你原本请求的模型。
x-zurelay-reasoning-effort仅在请求设置了推理级别时返回:模型实际使用的级别,即其支持的最接近的级别 (参见推理)。
x-zurelay-stopped仅在余额或密钥预算中途耗尽,或因剩余额度不足而调低 max_tokens 且回答达到该上限时返回: insufficient_quota、key_budget_exceeded 或 key_daily_budget_exceeded。返回的回答保留截至当时已生成的内容,并带有 finish_reason: "length"。

流式传输

设置 stream: true 后,回答会以服务端发送事件 (SSE) 的形式返回,使用 OpenAI 的分块格式,以 data: [DONE] 结束。各 SDK 都会自动解析这些事件。

import os
from openai import OpenAI
client = 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 os
from openai import OpenAI
client = 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 os
from openai import OpenAI
client = 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 OpenAI
client = 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].message
print(getattr(message, "reasoning_content", None)) # the thinking, when the model shares it
print(message.content)

对于公开思考内容的模型,思考内容会随回答一起通过 message.reasoning_content 返回 (流式响应中通过 delta.reasoning_content); 少数模型将该字段命名为 reasoning。思考内容按输出 token 计费,且始终计入 completion_tokens; 如果模型提供相应统计,completion_tokens_details.reasoning_tokens 会单独记录其数量。高推理强度下,回答可能需要数分钟才开始生成,因此请为客户端设置足够长的超时时间 (参见可靠性与超时)。

各模型的推理级别

以下信息来自各厂商的官方文档。如果指定的级别不受支持,会使用最接近的受支持级别 (若有两个同样接近的级别,则取较低者;只有传入 none 才会关闭思考),因此同一请求可用于所有模型,包括智能路由场景。x-zurelay-reasoning-effort 响应头会标明实际使用的级别。如果传入的词不属于任何推理级别,请求会被拒绝,并返回 400, 其中列出该模型支持的级别。

模型ID级别默认
Abliterated Large V2abliterated-large-v2low, high, maxmax
Claude Fable 5claude-fable-5low, medium, high, xhigh, maxhigh
Claude Fable 5.1claude-fable-5-1low, medium, high, xhigh, maxhigh
Claude Haiku 5.5claude-haiku-5-5low, medium, high, xhigh, maxmedium
Claude Opus 4.6claude-opus-4-6low, medium, high, max设置级别后才开启
Claude Opus 4.7claude-opus-4-7low, medium, high, xhigh, max设置级别后才开启
Claude Opus 4.8claude-opus-4-8low, medium, high, xhigh, max设置级别后才开启
Claude Opus 5claude-opus-5low, medium, high, xhigh, maxhigh
Claude Opus 5.5claude-opus-5-5low, medium, high, xhigh, maxmedium
Claude Sonnet 5.5claude-sonnet-5-5low, medium, high, xhigh, maxhigh
DeepSeek V4 Flashdeepseek-v4-flashnone, high, maxhigh
DeepSeek V4 Flash 0731deepseek-v4-flash-0731none, low, high, maxhigh
DeepSeek V4 Pro 0813deepseek-v4-pro-0813none, low, high, maxhigh
DeepSeek V4.1 Flashdeepseek-v4.1-flashnone, high, maxhigh
DeepSeek V4.1 Flash 1017deepseek-v4.1-flash-1017none, high, maxhigh
Gemini 3.1 Flash-Litegemini-3.1-flash-liteminimal, low, medium, highminimal
Gemini 3.1 Progemini-3.1-prolow, medium, highhigh
Gemini 3.5 Flash-Litegemini-3.5-flash-liteminimal, low, medium, highminimal
Gemini 3.7 Flashgemini-3.7-flashlow, medium, highmedium
Gemini 3.8 Flashgemini-3.8-flashlow, medium, highmedium
Gemini 4 Argongemini-4-argonlow, medium, highmedium
GLM-5.2glm-5.2none, high, maxmax
GLM-5.3glm-5.3low, high, maxmax
GLM-5.3 Flashglm-5.3-flashlow, high, maxmax
GLM-5.3 FlashXglm-5.3-flashxlow, high, maxmax
GPT-5.6 Lunagpt-5.6-lunanone, low, medium, high, xhigh, maxmedium
GPT-5.6 Solgpt-5.6-solnone, low, medium, high, xhigh, maxmedium
GPT-5.6 Terragpt-5.6-terranone, low, medium, high, xhigh, maxmedium
GPT-6 Astragpt-6-astralow, medium, high, xhigh, maxmedium
GPT-6 Lunagpt-6-lunanone, low, medium, high, xhigh, maxmedium
GPT-6 Solgpt-6-solnone, low, medium, high, xhigh, maxmedium
GPT-6.1 Solgpt-6.1-sollow, medium, high, xhigh, maxmedium
GPT-6.1 Terragpt-6.1-terranone, low, medium, high, xhigh, maxmedium
Grok 4.7grok-4.7low, medium, high, xhighhigh
HY4 Previewhy4-previewnone, highhigh
Kimi K2.5kimi-k2.5none, highhigh
Kimi K2.6kimi-k2.6none, highhigh
Kimi K3kimi-k3low, high, maxmax
Kimi K3.1 Prokimi-k3.1-prolow, high, maxmax
Kimi K3.1 Pro Highspeedkimi-k3.1-pro-highspeedlow, high, maxmax
MiMo V2.6 Flashmimo-v2.6-flashnone, highhigh
MiMo V2.6 Promimo-v2.6-pronone, highhigh
MiniMax M3minimax-m3none, highhigh
MiniMax M3.1 Flashminimax-m3.1-flashlow, medium, high, xhigh, maxmax
Muse Spark 1.3 Contributormuse-spark-1.3-contributorminimal, low, medium, high, xhighmedium
Muse Wondermuse-wonder-1.0minimal, low, medium, high, xhigh, maxhigh
Qwen 3.8 Flashqwen3.8-flashnone, low, medium, xhighxhigh
Qwen 3.8 Maxqwen3.8-maxnone, low, medium, xhighxhigh
Qwen 3.8 Omni Flashqwen3.8-omni-flashnone, low, medium, xhighxhigh
第 5 Preview 步step-5-previewlow, medium, highmedium
Zurelay Autozurelay-autonone, minimal, low, medium, high, xhigh, max设置级别后才开启
MiniMax M2.5minimax-m2.5无需设置始终开启思考
Claude Haiku 4.5claude-haiku-4-5无 (使用 Anthropic 格式的思考预算)关闭
Ministral 3 14Bministral-3-14b无关闭
Ministral 3 3Bministral-3-3b无关闭

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。

有疑问,或发现内容缺失?联系我们的支持团队,我们会通过邮件回复,通常只需一分钟。