配合 Comfy Router 使用 Chat Completions
通过 Comfy Router 调用 openrouter/chat-completions：端点、请求结构以及 Router 返回的响应。
配合 Comfy Router 使用 Chat Completions
通过 Comfy Router 调用 openrouter/chat-completions：端点、请求结构以及 Router 返回的响应。
openrouter/chat-completions 的 API 参考文档，由 Comfy Router 从 Openrouter 提供服务。
输入： 文本, 图像 · 输出： 文本
请求设置
在你的 Comfy 工作区中创建一个密钥，并将其导出为 COMFY_API_KEY。对于 Python，运行 pip install comfy-sdk。对于 TypeScript，运行 npm install @comfyorg/sdk。cURL 使用原始 HTTP。
模型 ID： openrouter/chat-completions
端点： POST https://api.comfy.org/v2/models/openrouter/chat-completions
[!NOTE] 此模型没有可运行的请求示例。请根据下方的输入文档构建请求体，然后配合 Router 快速入门使用。
Schema
输入
cache\_control object
启用自动提示词缓存。在顶层设置时，系统会自动将缓存断点应用到请求中最后一个可缓存的块。目前支持 Anthropic Claude 模型。
cache\_control.ttl string
可选值：5m、1h
cache\_control.type string required
可选值：ephemeral
debug object
用于检查请求转换的调试选项（仅限流式传输）
debug.echo\_upstream\_body boolean
如果为 true，则在流开始时将转换后的上游请求体包含在一个调试数据块中。仅在流式传输模式下有效。
frequency\_penalty number
频率惩罚（-2.0 到 2.0）
格式：double
image\_config object | string | number | object[]
logit\_bias object
Token logit 偏置调整
logprobs boolean
返回对数概率
max\_completion\_tokens integer
补全的最大 token 数
max\_tokens integer
最大 token 数（已弃用，请使用 max\_completion\_tokens）。注意：部分提供商会强制要求最小值为 16。
messages object[] required
对话的消息列表
metadata object
用于附加对象信息的键值对（最多 16 对，键最长 64 个字符，值最长 512 个字符）
modalities \\text, image, audio[]
响应的输出模态。支持的值为 "text"、"image" 和 "audio"。
model string
用于补全的模型
models string[]
用于补全的模型
parallel\_tool\_calls boolean
在使用工具时是否启用并行函数调用。为 true 时，模型可能在单次响应中生成多个工具调用。
plugins object[]
你想为此请求启用的插件，包括其设置。
presence\_penalty number
存在惩罚（-2.0 到 2.0）
格式：double
provider object
当有多个模型提供商可用时，可选择性地指明你的路由偏好。
provider.allow\_fallbacks boolean
是否允许备用提供商处理请求
- true：（默认）当主要提供商（或你在 "order" 中的自定义提供商）不可用时，使用次优的提供商。
- false：仅使用主要/自定义提供商，若其不可用则返回上游错误。
provider.data\_collection `deny, allow`
数据收集设置。如果没有可用的模型提供商满足该要求，你的请求将返回错误。
- allow：（默认）允许非临时存储用户数据并可能据此训练的提供商
- deny：仅使用不收集用户数据的提供商。
provider.enforce\_distillable\_text boolean
是否将路由限制为仅使用允许文本蒸馏的模型。为 true 时，仅使用作者已允许蒸馏的模型。
provider.ignore \\AkashML, AI21, AionLabs, Alibaba, Ambient, Baidu, Amazon Bedrock, Amazon Nova, Anthropic, Arcee AI, AtlasCloud, Avian, Azure, BaseTen, BytePlus, Black Forest Labs, Cerebras, Chutes, Cirrascale, Clarifai, Cloudflare, Cohere, Crucible, Crusoe, DeepInfra, DeepSeek, DekaLLM, Featherless, Fireworks, Friendli, GMICloud, Google, Google AI Studio, Groq, Hyperbolic, Inception, Inceptron, InferenceNet, Ionstream, Infermatic, Io Net, Inflection, Liquid, Mara, Mancer 2, Minimax, ModelRun, Mistral, Modular, Moonshot AI, Morph, NCompass, Nebius, Nex AGI, NextBit, Novita, Nvidia, OpenAI, OpenInference, Parasail, Poolside, Perceptron, Perplexity, Phala, Recraft, Reka, Relace, SambaNova, Seed, SiliconFlow, Sourceful, StepFun, Stealth, StreamLake, Switchpoint, Together, Upstage, Venice, WandB, Xiaomi, xAI, Z.AI, FakeProvider | string[]
要忽略的提供商 slug 列表。如果提供，此列表会与此请求中你账户级别的忽略提供商设置合并。
provider.max\_price object
用于指定你愿意为此请求支付的最高价格的对象。以美元计，每百万 token 的价格，针对提示词和补全。
provider.max\_price.audio string
每百万提示词 token 的价格
provider.max\_price.completion string
每百万提示词 token 的价格
provider.max\_price.image string
每百万提示词 token 的价格
provider.max\_price.prompt string
每百万提示词 token 的价格
provider.max\_price.request string
每百万提示词 token 的价格
provider.only \\AkashML, AI21, AionLabs, Alibaba, Ambient, Baidu, Amazon Bedrock, Amazon Nova, Anthropic, Arcee AI, AtlasCloud, Avian, Azure, BaseTen, BytePlus, Black Forest Labs, Cerebras, Chutes, Cirrascale, Clarifai, Cloudflare, Cohere, Crucible, Crusoe, DeepInfra, DeepSeek, DekaLLM, Featherless, Fireworks, Friendli, GMICloud, Google, Google AI Studio, Groq, Hyperbolic, Inception, Inceptron, InferenceNet, Ionstream, Infermatic, Io Net, Inflection, Liquid, Mara, Mancer 2, Minimax, ModelRun, Mistral, Modular, Moonshot AI, Morph, NCompass, Nebius, Nex AGI, NextBit, Novita, Nvidia, OpenAI, OpenInference, Parasail, Poolside, Perceptron, Perplexity, Phala, Recraft, Reka, Relace, SambaNova, Seed, SiliconFlow, Sourceful, StepFun, Stealth, StreamLake, Switchpoint, Together, Upstage, Venice, WandB, Xiaomi, xAI, Z.AI, FakeProvider | string[]
允许使用的提供商 slug 列表。如果提供，此列表会与你的账户级允许提供商设置合并，并应用于本次请求。
provider.order \\AkashML, AI21, AionLabs, Alibaba, Ambient, Baidu, Amazon Bedrock, Amazon Nova, Anthropic, Arcee AI, AtlasCloud, Avian, Azure, BaseTen, BytePlus, Black Forest Labs, Cerebras, Chutes, Cirrascale, Clarifai, Cloudflare, Cohere, Crucible, Crusoe, DeepInfra, DeepSeek, DekaLLM, Featherless, Fireworks, Friendli, GMICloud, Google, Google AI Studio, Groq, Hyperbolic, Inception, Inceptron, InferenceNet, Ionstream, Infermatic, Io Net, Inflection, Liquid, Mara, Mancer 2, Minimax, ModelRun, Mistral, Modular, Moonshot AI, Morph, NCompass, Nebius, Nex AGI, NextBit, Novita, Nvidia, OpenAI, OpenInference, Parasail, Poolside, Perceptron, Perplexity, Phala, Recraft, Reka, Relace, SambaNova, Seed, SiliconFlow, Sourceful, StepFun, Stealth, StreamLake, Switchpoint, Together, Upstage, Venice, WandB, Xiaomi, xAI, Z.AI, FakeProvider | string[]
按顺序排列的提供商 slug 列表。路由器会在此列表中支持你所请求模型的子集里，优先尝试第一个提供商；如果该提供商不可用，则回退到下一个。如果没有任何可用的提供商，请求将失败并返回报错信息。
provider.preferred\_max\_latency number | object
首选的最大延迟（单位为秒）。可以是一个数字（适用于 p50），也可以是带有各百分位特定阈值的对象。高于阈值的端点仍可能被使用，但在路由中会被降低优先级。使用回退模型时，如果回退模型满足阈值，可能会导致使用回退模型而不是主模型。
provider.preferred\_min\_throughput number | object
首选的最小吞吐量（单位为每秒 token 数）。可以是一个数字（适用于 p50），也可以是带有各百分位特定阈值的对象。低于阈值的端点仍可能被使用，但在路由中会被降低优先级。使用回退模型时，如果回退模型满足阈值，可能会导致使用回退模型而不是主模型。
provider.quantizations \\int4, int8, fp4, fp6, fp8, fp16, bf16, fp32, unknown[]
用于按量化级别过滤提供商的列表。
provider.require\_parameters boolean
是否将提供商过滤为仅保留那些支持你所提供参数的服务商。如果省略此设置或将其设为 false，提供商将只收到它们支持的参数，并忽略其余参数。
provider.sort \\price, throughput, latency, exacto | object
如果未指定 "order"，则使用此排序策略来处理本次请求。设置后，不会执行负载均衡。
provider.zdr boolean
是否将路由限制为仅使用 ZDR（零数据保留）端点。设为 true 时，只会使用不保留提示词的端点。
reasoning object
推理模型的配置选项
reasoning.effort `xhigh, high, medium, low, minimal, none`
限制推理模型在推理上投入的力度
reasoning.summary string
可能的值：auto、concise、detailed
response\_format object
响应格式配置
route object
任意类型
seed integer
用于生成确定性输出的随机种子
service\_tier `auto, default, flex, priority, scale`
用于处理此请求的服务层级。
session\_id string
用于对相关请求（例如一次对话或智能体工作流）进行分组以便可观测的唯一标识符。如果同时在请求体和 x-session-id 请求头中提供，则以请求体中的值为准。最多 256 个字符。
stop string | string[] | object
停止序列（最多 4 个）
stop\_server\_tools\_when object[]
服务器工具智能体循环的停止条件。任一条件触发都会终止循环（OR 逻辑）。设置后，此设置会覆盖 max_tool_calls。
stream boolean (default: false)
启用流式响应
stream\_options object
流式配置选项
stream\_options.include\_usage boolean
已弃用：此字段不产生任何效果。完整的用量详情始终会被包含。
temperature number
采样温度（0-2）
格式：double
tool\_choice \\none|auto|required | object
工具选择配置
tools object[]
可用于函数调用的工具
top\_logprobs integer
返回的 top log 概率数量（0-20）
top\_p number
核采样参数（0-1）
格式：double
trace object
用于可观测性和追踪的元数据。已知的键（trace\_id、trace\_name、span\_name、generation\_name、parent\_span\_id）有特殊处理。其他键会作为自定义元数据透传给已配置的广播目标。
trace.generation\_name string
trace.parent\_span\_id string
trace.span\_name string
trace.trace\_id string
trace.trace\_name string
user string
唯一用户标识符
根据 Router 在 GET /v2/models/openrouter/chat-completions/openapi.json 提供的 schema 生成，该文档与请求到达提供商之前 Router 用于校验调用的文档相同。
输出
choices object[] required
补全选项列表
choices\[].finish\_reason string required
可能的值：tool_calls、stop、length、content_filter、error
choices\[].index integer required
选项索引
choices\[].logprobs object
补全的对数概率
choices\[].logprobs.content object[] required
内容 token 的对数概率
choices\[].logprobs.content\[].bytes integer[] required
token 的 UTF-8 字节
choices\[].logprobs.content\[].logprob number required
token 的对数概率
格式：double
choices\[].logprobs.content\[].token string required
该 token
choices\[].logprobs.content\[].top\_logprobs object[] required
带概率的备选 token 排名
choices\[].logprobs.content\[].top\_logprobs\[].bytes integer[] required
choices\[].logprobs.content\[].top\_logprobs\[].logprob number required
格式：double
choices\[].logprobs.content\[].top\_logprobs\[].token string required
choices\[].logprobs.refusal object[]
拒绝 token 的对数概率
choices\[].logprobs.refusal\[].bytes integer[] required
token 的 UTF-8 字节
choices\[].logprobs.refusal\[].logprob number required
token 的对数概率
格式：double
choices\[].logprobs.refusal\[].token string required
该 token
choices\[].logprobs.refusal\[].top\_logprobs object[] required
带概率的备选 token 排名
choices\[].logprobs.refusal\[].top\_logprobs\[].bytes integer[] required
choices\[].logprobs.refusal\[].top\_logprobs\[].logprob number required
格式：double
choices\[].logprobs.refusal\[].top\_logprobs\[].token string required
choices\[].message object required
请求和响应的助手消息
choices\[].message.audio object
音频输出数据或引用
choices\[].message.audio.data string
Base64 编码的音频数据
choices\[].message.audio.expires\_at integer
音频过期时间戳
choices\[].message.audio.id string
音频输出标识符
choices\[].message.audio.transcript string
音频转写文本
choices\[].message.content string | object[] | object
助手消息内容
choices\[].message.images object[]
图像生成模型生成的图像
choices\[].message.images\[].image\_url object required
choices\[].message.images\[].image\_url.url string required
生成图像的 URL 或 base64 编码数据
choices\[].message.name string
助手的可选名称
choices\[].message.reasoning string
推理输出
choices\[].message.reasoning\_details object[]
扩展思考模型的推理详情
choices\[].message.refusal string
内容被拒绝时的拒绝消息
choices\[].message.tool\_calls object[]
助手发起的工具调用
choices\[].message.tool\_calls\[].function object required
choices\[].message.tool\_calls\[].function.arguments string required
JSON 字符串形式的函数参数
choices\[].message.tool\_calls\[].function.name string required
要调用的函数名称
choices\[].message.tool\_calls\[].id string required
工具调用标识符
choices\[].message.tool\_calls\[].type string required
可能的值：function
created integer required
创建时间的 Unix 时间戳
id string required
唯一的补全标识符
model string required
用于补全的模型
object string required
可能的值：chat.completion
openrouter\_metadata object
openrouter\_metadata.attempt integer required
openrouter\_metadata.attempts object[]
openrouter\_metadata.attempts\[].model string required
openrouter\_metadata.attempts\[].provider string required
openrouter\_metadata.attempts\[].status integer required
openrouter\_metadata.endpoints object required
openrouter\_metadata.endpoints.available object[] required
openrouter\_metadata.endpoints.available\[].model string required
openrouter\_metadata.endpoints.available\[].provider string required
openrouter\_metadata.endpoints.available\[].selected boolean required
openrouter\_metadata.endpoints.total integer required
openrouter\_metadata.is\_byok boolean required
openrouter\_metadata.params object
openrouter\_metadata.params.quality\_floor number
格式：double
openrouter\_metadata.params.throughput\_floor number
格式：double
openrouter\_metadata.params.version\_group string
openrouter\_metadata.pipeline object[]
openrouter\_metadata.pipeline\[].cost\_usd number
格式：double
openrouter\_metadata.pipeline\[].data object
openrouter\_metadata.pipeline\[].guardrail\_id string
openrouter\_metadata.pipeline\[].guardrail\_scope string
openrouter\_metadata.pipeline\[].name string required
openrouter\_metadata.pipeline\[].summary string
openrouter\_metadata.pipeline\[].type string required
流水线阶段的分类类型。多个插件可以共享同一个类型（例如所有 guardrail 级别的插件都会输出 guardrail）；name 字段用于区分具体是哪个插件输出的。
可能的值：guardrail、plugin、server_tools、response_healing、context_compression
openrouter\_metadata.region string required
openrouter\_metadata.requested string required
openrouter\_metadata.strategy string required
可能的值：direct、auto、free、latest、alias、fallback、pareto、bodybuilder、fusion
openrouter\_metadata.summary string required
service\_tier string
上游提供商为此请求使用的服务层级
system\_fingerprint string required
系统指纹
usage object
Token 使用量统计
usage.completion\_tokens integer required
补全内容中的 token 数量
usage.completion\_tokens\_details object
详细的补全 token 用量
usage.cost number
补全的费用
格式：double
usage.cost\_details object
上游推理费用的明细
usage.cost\_details.upstream\_inference\_completions\_cost number required
格式：double
usage.cost\_details.upstream\_inference\_cost number
格式：double
usage.cost\_details.upstream\_inference\_prompt\_cost number required
格式：double
usage.is\_byok boolean
该请求是否使用了自带密钥（Bring Your Own Key）配置
usage.prompt\_tokens integer required
提示词中的 token 数量
usage.prompt\_tokens\_details object
详细的提示词 token 用量
usage.total\_tokens integer required
token 总数
示例
输出
{
"choices": [
{
"finish_reason": "stop",
"index": 0,
"message": {
"content": "ok"
}
}
],
"created": 1750000000,
"id": "gen-0000000000-examplecompletion",
"model": "anthropic/claude-sonnet-4.5",
"object": "chat.completion",
"system_fingerprint": null,
"usage": {
"completion_tokens": 128,
"cost": 0.00123,
"prompt_tokens": 42,
"total_tokens": 170
}
}
发布前须知
SDK 会生成 Idempotency-Key 并在自动重试中复用它。手动重试时，请复用原始 key。Router 最长可保持连接 10 分钟。
请求失败时，Router 会发送 X-Comfy-Error-Type 响应头说明原因。422 表示 Router 在调用提供商之前就拒绝了输入，413 表示请求体超出了 Router 可接受的大小。已生成的资源请及时下载，因为结果 URL 会过期。
上文任何字段描述中提到的尺寸限制，都是提供商对该字段自身的限定，引自提供商的规范。Router 会对整个请求体另行设置上限，base64 编码的媒体内容也计入其中：参见请求体大小。
本页记录的是通过 Comfy Router 调用的某一个合作伙伴模型。同一个 comfy-sdk / @comfyorg/sdk 包还提供第二个客户端，用于在 Comfy Cloud 上运行完整的 ComfyUI 工作流图：Comfy(api_key=...) / new Comfy({ apiKey })，并带有 client.workflows、client.assets 和 client.jobs。请参阅 Comfy SDKs。
[card] 请求头 身份验证、幂等性、请求 ID、错误分类、重试节奏、消费限额。
[card] 使用 Router API 模型发现、验证错误、重试与计费。
[card] 限制 Router 目前不支持的功能，以及替代方案。