https://api.comfy.org
以下每个端点均需身份验证。请发送 Authorization: Bearer <jwt>。
端点
GET /v1/models
列出 Comfy Router 可以运行的模型。
Comfy Router 的模型目录：POST /v1/models/{provider}/{model} 所接受的规范模型 ID 的一页。SDK 在冷启动时调用此接口以发现可运行的模型，model_not_found 的建议也来自同一目录，因此，此处列出的 ID 在调用时返回 404 会比单独任一失败更糟糕。这种一致是结构性的，而非承诺：条目的 provider 和 model 是调用路由的两个路径段，引用与该路由路径参数相同的 schema 组件，而 id 是这两个段用 / 连接的结果。
参数
响应
按规范模型 ID 读取单个合作伙伴模型的目录条目。
单个 Comfy Router 模型的逐模型详情，调用方无需遍历整个分页目录即可查看某个模型。SDK 会在调用模型之前立即使用此端点来查找模型。
参数
响应
通过规范模型 ID 同步运行合作伙伴模型。
Comfy Router 的规范入口点，以模型 ID 寻址。请求体是合作伙伴模型自身的原生 JSON 输入，成功响应也是该模型自身的原生 JSON 输出：Router 原样转发两者，而非强加 Comfy 式封装，因此调用方只需更改主机即可在合作伙伴的 API 与 Router 之间切换。这是同步路径，与
POST https://fal.run/{id} 对应。响应携带已完成的结果。对应的队列端点 /v1/queue/models/{provider}/{model} 已在计划中，将把 fal 的 fal.run / queue.fal.run 拆分端点统一到同一主机上；该端点尚不属本契约的一部分。
参数
请求体
application/json — RouterModelInput（必填）
合作伙伴模型的原生 JSON 输入，原样转发给提供商。
响应
以 OpenAPI 文档形式读取单个合作伙伴模型的输入模式。
单个 Comfy Router 模型的输入模式，以独立的 OpenAPI 文档形式提供，使调用方（SDK、代码生成工具或智能体）无需阅读 Comfy 的文字说明文档即可发现模型的启动参数。它与 fal 的逐模型模式端点相对应，并且是 SDK 快速入门所依赖的发现机制。
参数
响应
错误分类桶
Router 失败的粗粒度机器可读分类桶，同时反映在X-Comfy-Error-Type 响应头中，以便调用方无需解析响应体即可进行分支处理。该集合固定为十五个值：六个请求级分类桶 invalid_input、content_policy_violation、provider_error、provider_timeout、insufficient_credits 和 model_not_found，以及传输级 unauthorized、forbidden、concurrency_limit_exceeded、client_disconnected、internal_error、deadline_exceeded、not_enabled、service_unavailable 和 rate_limited。
请求级分类桶
针对 Router 已接受但随后无法完成的请求抛出。传输级分类桶
由 Router 自身抛出，发生在调用模型之前或调用过程之中。响应头
各模型的输入模式
模型自身的输入字段不在此处重复列出。请通过GET /v1/models/{provider}/{model}/openapi.json 实时读取这些字段，该端点提供与服务器校验调用时所依据的同一份文档，因此对外发布的内容与强制执行的内容不会出现偏差。从 GET /v1/models 获取模型 ID，在其调用路径后附加 /openapi.json，然后根据返回的文档进行生成。
模式
RouterChargesOnPolicyRejection
模型因内容政策而拒绝的调用，是否仍会向调用方收费。各提供商的做法不同，这种差异在调用时不可见。用户看到同一次调用出现错误和扣费时，也无从事先知晓，因此该信息会在调用之前按模型逐一说明，而不是留给各提供商的口口相传。 类型：string### RouterErrorResponse
Router 的请求级错误体：当请求从未到达模型，或因模型本身未反馈的原因（认证、配额、未知模型 ID 或提供商传输）而失败时返回的内容。模型级验证失败具有自身的形状 RouterValidationErrorResponse，因为将 FastAPI 的 detail[] 数组扁平化为此 detail 字符串会破坏 SDK 所依赖的逐字段粒度。
粗粒度、机器可读的 Router 失败分类，同时镜像在
X-Comfy-Error-Type 响应头中，调用方无需解析响应体即可进行分支处理。该集合固定为十五个值：六个请求级分类 invalid_input、content_policy_violation、provider_error、provider_timeout、insufficient_credits 和 model_not_found，以及传输级 unauthorized、forbidden、concurrency_limit_exceeded、client_disconnected、internal_error、deadline_exceeded、not_enabled、service_unavailable 和 rate_limited。
类型：string### RouterModelBilling
调用方在发起调用之前需要了解的按模型计费的事实，而非价格。此处从不出现用量和费用数字。
某个 Comfy Router 模型的逐模型详细信息：目录列表为其报告的所有内容，外加仅单模型路由才包含的逐模型字段。
由
RouterModelListEntry 和 RouterModelDetailFields 组成。
类型：object### RouterModelDetailFields
RouterModelDetail 中目录列表并不包含的另一半：按模型区分的字段，值得单独查询一次，但无需在分页目录页面的每个条目上重复列出。
Comfy Router 模型的规范 ID 为
{provider}/{model}，这正是 POST /v1/models/{provider}/{model} 上用于寻址该模型的值，因此调用方可以将其直接插入该路径，而无需从任何其他内容重新推导。其 pattern 由 RouterProviderSegment 和 RouterModelSegment 通过单个 / 连接而成，maxLength 为两者之和再加上该分隔符。
类型：string，pattern: ^[a-z0-9]+([._-][a-z0-9]+)*/[a-z0-9]+([._-][a-z0-9]+)*$，maxLength: 193### RouterModelInput
合作伙伴模型的原生 JSON 输入文档，按原样转发给提供商。其具体形状由合作伙伴而非 Comfy 拥有，因此这是一个开放对象：Router 不会缩窄、重命名或重新封装这些字段。它是一个命名组件（绝不会是内联匿名对象），因为 ComfyUI 的规范驱动代码生成需要一个类来生成。
类型：object### RouterModelInputSchemaDocument
一个独立的 OpenAPI 文档，描述单个 Comfy Router 模型的输入：即 POST /v1/models/{provider}/{model} 针对该模型接受的请求体。它正是 GET /v1/models/{provider}/{model}/openapi.json 所返回的内容。
类型：object### RouterModelListEntry
Router 模型目录中的一条条目：可运行模型的身份标识，仅此而已。按模型的详情路由会复用这条相同的条目，而不是重新陈述，这正是名称使用 ...ListEntry 而非 ...Summary 的原因：目录条目的定义必须唯一。按模型的详情以及按模型的输入/输出模式（schema）各有独立的路由，因此此形状保持为调用方调用模型所需的最小信息。这是有意为之，因为这是 SDK 在冷启动时获取的负载。id 是 provider 和 model 以 / 连接而成；这两个字段也分别携带，以便调用方无需拆分字符串即可拼出调用路径。
Router 模型目录中的一页。
合作伙伴模型的原生 JSON 输出文档，原样返回给调用方。其具体形状由合作伙伴而非 Comfy 定义，因此这是一个开放对象：Router 不会对字段进行收窄、重命名或重新封装。它是一个命名组件（绝不是内联匿名对象），因为 ComfyUI 的规范驱动代码生成需要一个类来生成。
类型：
object### RouterModelSegment
规范的 {provider}/{model}[/{variant}] 模型 ID 中的小写 model 段，表示要在该提供商内运行的模型。调用路由的 model 路径参数与目录条目的 model 字段共享此段，原因与 RouterProviderSegment 相同，即防止漂移。
类型：字符串，pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$，maxLength: 128### RouterPageCursor
Router 列表的一个不透明游标。它由服务器生成，且仅用于往返传递：它不是偏移量，不是模型 ID，不保证有序，也不会在目录重建后保持稳定。因此，解析游标、递增游标，或将游标持久化到超出其来源遍历的范围之外，均不在契约范围之内。之所以使用游标而非偏移量，是因为目录是一个动态变化的列表：在遍历过程中添加或删除条目时，基于偏移量的遍历会静默跳过或重复条目，而调用方无法察觉这种情况的发生。
类型：string（pattern: ^[A-Za-z0-9._~+/=-]+$、minLength: 1、maxLength: 512）### RouterProviderSegment
规范模型 ID {provider}/{model}[/{variant}] 中的小写 provider 段，表示其模型正被寻址的合作伙伴。调用路由的 provider 路径参数和目录条目的 provider 字段均引用此同一模式，这正是确保所列 ID 与所接受 ID 不会发生偏离的原因。
类型：string。pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$，maxLength: 64### RouterValidationErrorContext
某个 RouterValidationErrorDetail 的违规边界，由提供商原样传递。例如，{"limit_value": 8} 对应 greater_than，{"min_width": 512} 对应 image_too_small，或 {"max_size_bytes": 10485760} 对应 file_too_large。键集因提供商和错误类型而异，因此该对象刻意设计为开放对象。将其收窄为固定字段列表，或将其并入 msg 字符串，正是移植集成得以编译通过、却随后悄然丢失读取该边界的代码分支的方式。当错误类型不携带边界时，此字段缺失。
类型：object### RouterValidationErrorDetail
以 fal/FastAPI 形式表示的单次模型级验证失败。type 携带的是提供商的特定原因，例如 value_error、missing、image_too_small、unsupported_audio_format、greater_than、file_too_large 等等，这是 RouterErrorType 的粗粒度分类所无法表达的细节层次。出于同样的原因，它是一个开放字符串而非 enum：提供商的词汇表跨越两个层级，约有 48 个值，并随提供商的发布周期增长，而不是我们的发布周期。未建模的值必须能够到达调用方，而不是在反序列化时失败。
违规的输入值，原样回显，以便调用方无需从
loc 重新推导即可看到被拒绝的内容。可以是任何 JSON 类型：字符串、数字、布尔、数组、对象或 null。因此此 schema 特意保持无类型，而不是限定为对象。当提供商不回显输入时，此字段不存在。### RouterValidationErrorResponse
Router 的模型级 422 响应体，采用 fal/FastAPI 形式：请求格式良好，足以到达模型，但模型拒绝了其内容。请注意，它本身不携带 error_type 字段，这正是响应中的 X-Comfy-Error-Type 标头的用途：客户端无需先判断收到的是两个 Router 错误响应体中的哪一个，即可从标头读取粗略的错误分类。