跳转到主要内容
Wan 2.5 I2V 预览的 API 参考。Wan 2.5 图生视频可将一张静态首帧图像转换为一段短视频,其中的运动与相机运镜由提示词描述。 输入: 图像, 音频, 文本 · 输出: 视频 + 音频

快速开始

在你的 Comfy 工作区中创建一个密钥,并将其导出为 COMFY_API_KEY。Python 和 TypeScript 代码片段使用 Comfy SDK(pip install comfy-sdk 和 npm install @comfyorg/sdk);cURL 代码片段则通过原始 HTTP 发起同样的调用。 模型 ID: wan/wan2.5-i2v-preview 端点: POST https://api.comfy.org/v2/models/wan/wan2.5-i2v-preview
同一请求体,发送至 POST https://api.comfy.org/v2/models/wan/wan2.5-i2v-preview/requests。运行一旦被接纳,Router 就会返回 201 和一个 request_id,结果就绪后再进行收集,可由本进程或另一个进程完成。队列投递 详细介绍了状态、取消和收集。

Schema

输入

object
必填
填写基本信息,如提示词等。
string
音频文件下载 URL。支持的格式:mp3 和 wav。不能与 reference_video_urls 一起使用。
string
首帧图像 URL 或 Base64 编码数据。wan2.5-i2v-preview 和 wan2.6-i2v 模型必填。happyhorse-1.x 的 i2v 写法不在此处接收首帧,它们把首帧作为 type 为 first_frame 的 media 元素传入(见下方的 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。
object[]
媒体资产列表。用于指定视频生成的参考素材(图像、音频、视频)。每个元素包含一个 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,可以是公开 URL 或 data:{MIME_type};base64,… URL。 driving_audio(WAV/MP3,2-30 秒,最大 15MB)和 first_clip(MP4/MOV,2-10 秒,每边 240-4096 像素,最大 100MB):公开的 HTTP/HTTPS URL;不接受内联 data: URL。
  • wan2.7-r2v:first_frame(可选,最多 1 个)、reference_image、reference_video。至少需要 一个 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,可以是公开 URL 或 data:{MIME_type};base64,… URL。reference_video:公开的 HTTP/HTTPS URL;不接受内联 data: URL。
  • wan2.7-videoedit:video(恰好 1 个,即被编辑的片段:MP4/MOV,2-10 秒, 每边 240-4096 像素,最大 100MB,公开的 HTTP/HTTPS URL;不接受内联 data: URL) 外加可选的 0 到 4 个 reference_image(JPEG/JPG/PNG/BMP/WEBP, 每边 240-8000 像素,宽高比在 1:8 到 8:1 之间,最大 20MB,可以是公开 URL 或 data:{MIME_type};base64,… URL)。
  • 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 类型在同一请求内互斥。数组顺序决定 提示词中资产的参考顺序(Image 1、Video 1、Audio 1……)。first_frame、last_frame 和 reference_image:JPEG/JPG/PNG/BMP/WEBP,每边 240-8000 像素,宽高比最大 8:1, 最大 20MB,可以是公开 URL 或 data:{MIME_type};base64,… URL。reference_video、 reference_audio、file 和 link:公开的 HTTP/HTTPS URL;不接受内联 data: URL。
  • 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,可以是公开 URL 或 data:{MIME_type};base64,… URL。
  • happyhorse-1.0-r2v、happyhorse-1.1-r2v:仅 reference_image,1 到 9 个。这是 该模型唯一的参考输入。最短边至少 400 像素,JPEG/JPG/PNG/WEBP, 最大 20MB,可以是公开 URL 或 data:{MIME_type};base64,… URL。reference_video 不是此操作的输入类型。
  • happyhorse-1.0-video-edit:video(恰好 1 个,即被编辑的片段:MP4/MOV,3-60 秒,长边最大 4096 像素,短边至少 360 像素,宽高比 在 1:2.5 到 2.5:1 之间,最大 100MB,公开的 HTTP/HTTPS URL;不接受内联 data: URL)外加可选的 0 到 5 个 reference_image(JPEG/JPG/PNG/WEBP,至少 300x300 像素,宽高比在 1:2.5 到 2.5:1 之间,最大 20MB,可以是公开 URL 或 data:{MIME_type};base64,… URL)。
  • 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”的数字(图像输入的上限,也是唯一可能内联发送的 输入),是合作伙伴对其最终获得的资产设定的上限,当资产是公开 URL 时按字面适用, 因为这些字节从不经过 Comfy。内联的 data:{MIME_type};base64,… URL 确实会经过 Comfy,因此还会遇到传输上限:Comfy Router 的 POST 请求体总计上限为 100 MiB,超过即返回 413,而 base64 会使 负载膨胀约 4/3,因此单个内联资产超过约 75 MB 时,就会在触达这里的任何 合作伙伴规则之前被拒绝。在这种大小下,单个资产达到合作伙伴自身 20MB 的上限,以内联方式发送也绰绰有余,因此单个资产受合作伙伴规则的约束,而多个资产则受传输上限的约束,因为 Router 的 100 MiB 上限约束的是整个请求,而不是每个元素。接近这些上限的任何内容请以公共 URL 发送。
string
必填
媒体资产类型可选值:first_frame、last_frame、driving_audio、first_clip、reference_image、reference_video、reference_audio、video、file、link
string
必填
媒体文件的 URL:一个公共 HTTP/HTTPS URL;或者,仅限上文 media 描述中为各模型列出的那些 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),一个内联的 data:{MIME_type};base64,... URL。这些模型中没有任何视频、音频、文件或链接输入接受内联 data: URL。来自合作伙伴自有上传服务的 oss://dashscope-instant 临时 URL,或(在 wan2.7-videoedit 上)Asset Center 的 asset_id,只会对上传它的阿里云账号生效;Comfy 使用自己的密钥发起模型调用,不提供上传路由,因此调用方自己的 oss:// URL 或 asset_id 不是受支持的输入。此字段不校验 URL 协议,因此这类值会原样转发给合作伙伴,而不会在这里被拒绝。各模型的大小与像素限制,以及约束内联载荷总量的 Router 请求体 100 MiB 上限,请参见 media 描述。
string
反向提示词用于描述你不希望在视频画面中看到的内容。超过 500 个字符时,Wan 模型会将其截断,而不是拒绝它。它与 prompt 计入同一输入预算。
string
文本提示词。支持中文和英文。超过各自文档规定的长度时,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 的参考模式,请按 media 数组中相应的顺序使用 ‘Image 1’、‘Video 1’、‘Audio 1’ 等来指代媒体资产。
string[]
仅用于 wan2.6-r2v 模型的参考视频 URL。由 1-3 个视频 URL 组成的数组。 输入限制:
  • 格式:mp4、mov
  • 数量:1-3 个视频
  • 单个视频长度:2-30 秒
  • 单个文件大小:最大 30MB
  • 不能与 audio_url 一起使用 参考时长:单个视频最长 5 秒,两个视频各最长 2.5 秒,三个视频按比例更短。 计费:按实际使用的参考时长计算。
string
视频效果模板名称。可选。当前支持:squish、flying、carousel。使用时,prompt 参数将被忽略。
string
要调用的模型 ID。此组件不作约束:Comfy Router 会从 POST /v2/models/wan/{model} 的 {model} 路径段填充它,因此 Router 调用方会省略它。直接对 POST /proxy/wan/api/v1/services/aigc/video-generation/video-synthesis 发起的 v1 调用则必须提供它,可接受拼写的枚举位于该操作自己的组件 WanVideoGenerationRequest 上。
object
视频处理参数
boolean
默认值:"true"
是否为视频添加音频。仅 wan3.0-video 和 wan3.0-video-prime 支持;提供商未为其他 Wan 模型记录此类切换。
string
默认值:"\"auto\""
wan2.7-videoedit 模型的视频音频设置。
  • auto(默认):模型根据提示词内容智能判断
  • origin:强制保留输入视频的原始音频 可选值:auto、origin
integer
默认值:"5"
生成视频的时长,以秒为单位:
  • wan2.5 模型:5 或 10 秒
  • wan2.6-t2v、wan2.6-i2v:5、10 或 15 秒
  • wan2.6-r2v:仅 5 或 10 秒(不支持 15 秒)
  • wan2.7-i2v、wan2.7-t2v:[2, 15] 范围内的整数
  • wan2.7-r2v、wan2.7-videoedit:[2, 10] 范围内的整数
  • wan3.0-video:无视频输入时为 [2, 30] 范围内的整数;有视频输入时,输入视频时长与输出视频时长之和不得超过 30 秒;-1 启用智能时长模式,由模型选择合适的时长 该代理对超出 [-1, 30] 范围的 duration 返回 400。 范围:-1 至 30
boolean
默认值:"true"
是否启用提示词智能改写。默认为 true
string
生成视频的宽高比。仅适用于 wan2.7 和 wan3.0 模型。 对于 wan2.7 模型,若未提供则根据分辨率档位取默认值。 对于 wan3.0-video,adaptive(默认值)会根据输入媒体的比例和意图自动推荐合适的宽高比。可选值:adaptive, 16:9, 9:16, 1:1, 4:3, 3:4
string
分辨率档位。支持的值因模型而异:
  • 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 模型,对 480P(无论是以 resolution 还是以 480P 的 size 发送)返回 400。 可选值:480P, 720P, 1080P
integer
随机数种子,用于控制模型生成内容的随机性范围:0 到 2147483647
string
默认值:"\"single\""
智能多镜头控制。仅在启用 prompt_extend 时生效。 适用于 wan2.6 和 wan2.7-r2v 模型。
  • single:单镜头视频(默认)
  • multi:多镜头视频 可选值:multi, single
string
视频分辨率,格式为 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。
boolean
默认值:"false"
是否添加水印标志,水印位于右下角
根据 Router 在 GET /v2/models/wan/wan2.5-i2v-preview/openapi.json 提供的 schema 生成,该文档也是请求到达提供商之前校验调用时所依据的同一份文档。

输出

object
必填
string
智能改写后的实际提示词(视频任务)
string
带音频生成的 I2V 任务的音频网址
string
失败请求的错误码(请求成功时不返回)
string
任务完成时间
string
失败请求的详细信息(请求成功时不返回)
string
原始输入提示词(视频任务)
object[]
图像生成任务的结果列表
string
智能改写后的实际提示词(若已启用)
string
图像错误码(部分任务失败时返回)
string
图像错误信息(部分任务失败时返回)
string
原始输入提示词
string
已生成图像的网址
string
任务执行时间
string
任务提交时间
string
必填
任务 ID
object
图像生成任务的统计结果
integer
失败任务数
integer
成功任务数
integer
任务总数
string
必填
任务状态可选值:PENDING、RUNNING、SUCCEEDED、FAILED、CANCELED、UNKNOWN
string
已完成的视频生成任务的视频网址。链接有效期 24 小时
string
必填
唯一请求标识符
object
输出信息统计。仅统计成功的结果
integer
视频分辨率等级(I2V 和 wan3.0-video 任务)
number
已生成视频的时长,单位为秒(I2V 和 wan3.0-video 任务)
integer
已生成视频的帧率(wan3.0-video 任务)
integer
已生成图像的数量(T2I 和 I2I 任务)
number
输入视频的时长,单位为秒;无视频输入时为 0.0(wan3.0-video 任务)
number
输出视频的时长,单位为秒(wan3.0-video 任务)
string
已生成视频的宽高比,例如 16:9(wan3.0-video 任务)
string
图像分辨率(T2I 和 I2I 任务)
integer
已生成视频的数量(T2V 任务)
number
已生成视频的时长,单位为秒(T2V 任务)
string
视频分辨率比例(T2V 任务)
string
失败请求的错误码,在响应外层结构的根层级报告,而不是在 output 下报告(请求成功时不返回)。
string
失败请求的详细信息,在响应外层结构的根层级报告,而不是在 output 下报告(请求成功时不返回)。在回退到 output.message 之前,请先读取此项。

示例

输入

输出

视频 URL 的有效期为 24 小时。如需保留该视频,请及时下载。

发布前须知

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 目前不支持的功能,以及替代方案。