快速开始
在你的 Comfy 工作区中创建密钥,并将其导出为COMFY_API_KEY。Python 和 TypeScript 代码片段使用 Comfy SDK(pip install comfy-sdk 和 npm install @comfyorg/sdk);cURL 代码片段则是通过原始 HTTP 发出的同一调用。
模型 ID: wan/wan2.7-t2v
端点: POST https://api.comfy.org/v2/models/wan/wan2.7-t2v
- 等待结果
- 排队并稍后收集
相同的请求体,发送到
POST https://api.comfy.org/v2/models/wan/wan2.7-t2v/requests。一旦运行被接纳,Router 便会返回 201 和 request_id,运行就绪后即可收集结果,可以来自当前进程,也可以来自另一个进程。队列投递完整介绍了状态、取消与收集的流程。Schema
输入
首帧图像网址或 Base64 编码数据。wan2.5-i2v-preview 和 wan2.6-i2v 模型必须提供此字段。happyhorse-1.x
的 i2v 写法不在此处接收首帧:它们将首帧作为类型为 first_frame 的媒体元素接收(见下方
media),而在 wan2.6-i2v 上能够成功的 img_url 请求体,在
happyhorse-1.0-i2v 和 happyhorse-1.1-i2v 上会被提供商拒绝;wan2.7/wan3.0 的写法同样在 media 中
提供其参考资产。图像格式:JPEG、JPG、PNG、BMP、WEBP。
分辨率:360-2000 像素。文件大小:最大 10MB。
媒体资产列表。指定用于视频生成的参考素材(图像、音频、视频)。每个元素包含 type 和 url 字段。此字段由该组件提供的所有模型共用,而某个给定模型接受哪些 type
值,以及它究竟是在此处还是在 img_url 或 reference_video_urls 中携带其图像或视频输入,会因模型
而异。各模型支持的 type 值如下:
- wan2.7-i2v:first_frame、last_frame、driving_audio、first_clip。first_frame 和 last_frame:JPEG/JPG/PNG/BMP/WEBP,每边 240-8000 像素,宽高比介于 1:8 与 8:1 之间,最大 20MB,可为公开网址或 data:{MIME_type};base64,… 网址。 driving_audio(WAV/MP3,2-30 秒,最大 15MB)和 first_clip(MP4/MOV,2-10 秒,每边 240-4096 像素,最大 100MB):公开 HTTP/HTTPS 网址;不接受内联 data: 网址。
- wan2.7-r2v:first_frame(可选,最多 1 个)、reference_image、reference_video。至少需要 一个 reference_image 或 reference_video,且参考图像加上 参考视频总计最多 5 个。first_frame 和 reference_image:JPEG/JPG/PNG/BMP/WEBP (无透明度通道),每边 240-8000 像素,宽高比介于 1:8 与 8:1 之间,最大 20MB,可为公开网址或 data:{MIME_type};base64,… 网址。reference_video:公开 HTTP/HTTPS 网址;不接受内联 data: 网址。
- wan2.7-videoedit:video(恰好 1 个,即被编辑的片段:MP4/MOV,2-10 秒, 每边 240-4096 像素,最大 100MB,公开 HTTP/HTTPS 网址;不接受内联 data: 网址) 外加可选的 0 到 4 个 reference_image(JPEG/JPG/PNG/BMP/WEBP, 每边 240-8000 像素,宽高比介于 1:8 与 8:1 之间,最大 20MB,可为公开网址 或 data:{MIME_type};base64,… 网址)。
- wan3.0-video、wan3.0-video-prime:first_frame(最多 1 个)、last_frame(最多 1 个)、 reference_image(最多 10 个)、reference_video(最多 5 个片段,总时长 <= 15s)、 reference_audio(最多 5 个片段,总时长 <= 15s)、file(最多 1 个,不能与 link 同时使用)、link(最多 1 个,不能与 file 同时使用)。reference_*/file/link 类型 与 first_frame/last_frame 类型在同一请求中互斥。数组 顺序决定提示词中资产的引用顺序(图像 1、视频 1、音频 1……)。first_frame、last_frame 和 reference_image:JPEG/JPG/PNG/BMP/WEBP,每边 240-8000 像素,宽高比最多 8:1, 最大 20MB,可为公开网址或 data:{MIME_type};base64,… 网址。reference_video、 reference_audio、file 和 link:公开 HTTP/HTTPS 网址;不接受内联 data: 网址。
- happyhorse-1.0-i2v、happyhorse-1.1-i2v:仅 first_frame,恰好 1 个。这些写法 在此处接收首帧,而不是在 img_url 中。至少 300x300 像素,宽高比 介于 1:2.5 与 2.5:1 之间,JPEG/JPG/PNG/WEBP,最大 20MB,可为公开网址或 data:{MIME_type};base64,… 网址。
- happyhorse-1.0-r2v、happyhorse-1.1-r2v:仅 reference_image,1 到 9 个。这是 该模型唯一的参考输入。最短边至少 400 像素,JPEG/JPG/PNG/WEBP, 最大 20MB,可为公开网址或 data:{MIME_type};base64,… 网址。reference_video 不是此操作的输入类型。
- happyhorse-1.0-video-edit:video(恰好 1 个,即被编辑的片段:MP4/MOV,3-60 秒,较长边最多 4096 像素,较短边至少 360 像素,宽高比 介于 1:2.5 与 2.5:1 之间,最大 100MB,公开 HTTP/HTTPS 网址;不接受内联 data: 网址)外加可选的 0 到 5 个 reference_image(JPEG/JPG/PNG/WEBP,至少 300x300 像素,宽高比介于 1:2.5 与 2.5:1 之间,最大 20MB,可为公开网址 或 data:{MIME_type};base64,… 网址)。
- happyhorse-1.0-t2v、happyhorse-1.1-t2v、wan2.7-t2v、wan2.6-t2v、wan2.5-t2v-preview: 文生视频操作。它们的合作伙伴参考文档未记载任何媒体输入,因此请 不要设置此字段。
- wan2.5-i2v-preview、wan2.6-i2v、wan2.6-r2v:本组件未为这些写法枚举任何 media 词汇。wan2.5-i2v-preview 和 wan2.6-i2v 在 img_url 中提供其首 帧;wan2.6-r2v 在 reference_video_urls 中提供其参考片段。 上文按模型列出的数量是合作伙伴的限制,而非本 Schema 的限制:media 上没有声明 minItems/maxItems,因为可接受的类型及其上限 因模型而异。Schema 接受并不代表提供商接受;反过来, 上文每项资产“最大 20MB”的数字(图像 输入的上限,也是唯一可以内联发送的输入)是合作伙伴对其最终 收到的资产的限制,当资产为公开网址时,这些限制按字面生效, 因为这些字节从不经过 Comfy 传输。内联的 data:{MIME_type};base64,… 网址确实会经过 Comfy 传输,也会遇到传输限制:Comfy Router 的 POST 请求体总大小上限为 100 MiB,超过则返回 413,而 base64 会使 负载增大约 4/3,因此单个超过约 75 MB 的内联资产会在触及此处任何合作伙伴规则 之前就被拒绝。在这种大小下,单个资产处于合作伙伴自身的20MB 的上限足以轻松容纳内联数据,因此对于单个资产,真正起约束作用的是合作伙伴的规则;而当涉及多个资产时,起约束作用的则是传输上限,因为 100 MiB 的 Router 上限约束的是整个请求,而不是其中的每个元素。任何接近这些上限的内容,都请以公共 URL 的形式发送。
媒体资产类型可选值:
first_frame、last_frame、driving_audio、first_clip、reference_image、reference_video、reference_audio、video、file、link媒体文件的 URL:可以是公共 HTTP/HTTPS URL;或者,仅针对上文
media 描述中为各模型列出的 IMAGE 输入,才可以是内联的 data:{MIME_type};base64,... URL。这些 IMAGE 输入为:wan2.7-i2v 上的 first_frame 和 last_frame;wan2.7-r2v 上的 first_frame 和 reference_image;wan2.7-videoedit 上的 reference_image;wan3.0-video 和 wan3.0-video-prime 上的 first_frame、last_frame 和 reference_image;happyhorse-1.0-i2v 和 happyhorse-1.1-i2v 上的 first_frame;happyhorse-1.0-r2v 和 happyhorse-1.1-r2v 上的 reference_image;以及 happyhorse-1.0-video-edit 上的 reference_image。在上述任何模型上,video、audio、file 或 link 输入都不接受内联的 data: URL。来自合作伙伴自有上传服务的 oss://dashscope-instant 临时 URL,或者(在 wan2.7-videoedit 上)Asset Center 的 asset_id,只会对上传它的那个阿里云账号生效;Comfy 使用自己的密钥发起模型调用,并且不提供任何上传途径,因此调用方自有的 oss:// URL 或 asset_id 不是受支持的输入。此字段不校验 URL 的协议,因此这类值会被原样转发给合作伙伴,而不会在这里被拒绝。有关各模型的尺寸与像素限制,以及约束内联载荷总量的 100 MiB Router 请求体上限,请参阅 media 描述。文本提示词。支持中文和英文。超过各自文档所记载的长度时,wan2.x 模型会截断提示词,而不是拒绝请求:wan2.5 和 wan2.6 为 1,500 个字符,wan2.7 为 5,000 个字符。wan3.0-video 和 wan3.0-video-prime 最多接受 20,000 个字符。若 prompt 与 negative_prompt 合计超过约 60,850 字节的 UTF-8 文本(约 20,000 个汉字),提供商会拒绝该请求,并返回 InvalidParameter
Range of input length should be [1, 61440]。
对于带多个参考视频的 wan2.6-r2v,请按参考视频的顺序使用 ‘character1’、‘character2’ 等来指代主体。示例:“Character1 sings on the roadside, Character2 dances beside it”
对于 wan3.0-video 的参考模式,请使用 ‘Image 1’、‘Video 1’、‘Audio 1’ 等,按媒体数组中的对应顺序来指代媒体资产。仅用于 wan2.6-r2v 模型的参考视频 URL。1-3 个视频 URL 组成的数组。
输入限制:
- 格式:mp4、mov
- 数量:1-3 个视频
- 单个视频时长:2-30 秒
- 单个文件大小:最大 30MB
- 不能与 audio_url 同时使用 参考时长:单个视频最长 5s,两个视频各最长 2.5s,三个视频按比例更短。 计费:按实际使用的参考时长计费。
要调用的模型 ID。此组件上不做约束:Comfy Router 会从
POST /v2/models/wan/{model} 的 {model} 路径片段中填充它,因此 Router 调用方会省略该字段。直接以 v1 调用 POST /proxy/wan/api/v1/services/aigc/video-generation/video-synthesis 时则必须提供它,可接受的拼写枚举位于该操作自身的组件 WanVideoGenerationRequest 上。wan2.7-videoedit 模型的视频音频设置。
- auto(默认):模型根据提示词内容智能判断
-
origin:强制保留输入视频的原始音频
可选值:
auto、origin
生成视频的时长,单位为秒:
- wan2.5 模型:5 或 10 秒
- wan2.6-t2v、wan2.6-i2v:5、10 或 15 秒
- wan2.6-r2v:仅 5 或 10 秒(不支持 15s)
- wan2.7-i2v、wan2.7-t2v:[2, 15] 范围内的整数
- wan2.7-r2v、wan2.7-videoedit:[2, 10] 范围内的整数
-
wan3.0-video:无视频输入时为 [2, 30] 范围内的整数;有视频输入时,总输入视频时长
与输出视频时长之和不得超过 30 秒;-1 会启用智能时长模式,由模型自行选择合适的时长
当 duration 超出 [-1, 30] 时,此代理会返回 400。
范围:
-1到30
生成视频的宽高比。仅适用于 wan2.7 和 wan3.0 模型。
对于 wan2.7 模型,如果未提供,则根据分辨率档位取默认值。
对于 wan3.0-video,adaptive(默认值)会根据输入媒体的比例和意图自动推荐合适的宽高比。可选值:
adaptive、16:9、9:16、1:1、4:3、3:4分辨率档位。支持的取值因模型而异:
- wan2.5-i2v-preview:480P、720P、1080P
- wan2.6 系列模型(t2v、i2v、r2v):仅 720P、1080P(不支持 480P)
- wan2.7 系列模型(i2v、t2v、r2v、videoedit):720P、1080P(默认 1080P)
- wan3.0-video、wan3.0-video-prime:480P、720P、1080P(上游默认 1080P)
- happyhorse-1.0-*(t2v、i2v、r2v、video-edit):720P、1080P
-
happyhorse-1.1-*(t2v、i2v、r2v):480P、720P、1080P
本代理会拒绝既未提供 resolution 也未提供 size 的视频生成请求,因为分辨率档位决定计费费率。它会在校验之前先把 resolution 转为大写并转发该大写值,对于不在该枚举范围内的取值返回 400,并且对上文列为不支持 480P 的 wan2.6、wan2.7 和 happyhorse-1.0 模型返回 400(无论是以 resolution 还是以 480P 的 size 发送)。
可选值:
480P、720P、1080P
智能多镜头控制。仅在启用 prompt_extend 时生效。适用于 wan2.6 和 wan2.7-r2v 模型。
- single:单镜头视频(默认)
-
multi:多镜头视频
可选值:
multi、single
视频分辨率,格式为 widthheight。支持的分辨率因模型而异:
对于 wan2.5 T2V:480P(480832、832480、624624)、720P、1080P 尺寸
对于 wan2.6 T2V/R2V(不支持 480P):
720P:1280720、7201280、960960、1088832、8321088
1080P:19201080、10801920、14401440、16321248、12481632
当同时发送 size 和 resolution 时,由 size 决定计费档位,而 resolution 仍必须是本代理为该模型所接受的取值。对于分辨率描述中列为不支持 480P 的每个模型,480P 的 size 都会返回 400。
GET /v2/models/wan/wan2.7-t2v/openapi.json 提供的 schema 生成,这也是请求到达提供商之前用于校验调用的同一份文档。
输出
示例
输入
输出
发布前须知
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。
请求头
身份验证、幂等性、请求 ID、错误分类、重试节奏、消费限额。
使用 Router API
模型发现、验证错误、重试与计费。
限制
Router 目前不支持的功能,以及替代方案。