Skip to main content
HappyHorse 1.0 I2V 的 API 参考。HappyHorse 1.0 图生视频可将静止的首帧制作成动画,并在同一次处理中渲染同步音频。

快速开始

你的 Comfy 工作区中创建密钥,并将其导出为 COMFY_API_KEY。Python 和 TypeScript 代码片段使用 Comfy SDK(pip install comfy-sdknpm install @comfyorg/sdk);cURL 代码片段则是通过原始 HTTP 进行的同一调用。 模型 ID: wan/happyhorse-1.0-i2v 端点: POST https://api.comfy.org/v2/models/wan/happyhorse-1.0-i2v

数据结构

输入

object
必填
填写基本信息,例如提示词等。
string
音频文件下载网址。支持的格式:mp3 和 wav。不能与 reference_video_urls 一起使用。
string
首帧图像网址或 Base64 编码数据。仅 wan2.5-i2v-preview 与 wan2.6-i2v 模型需要该参数。happyhorse-1.x 的 i2v 写法不在此处传入首帧:它们把首帧作为 media 中 type 为 first_frame 的元素传入(见下方 media 说明),一个在 wan2.6-i2v 上能成功的 img_url 请求体,会被提供方在 happyhorse-1.0-i2v 与 happyhorse-1.1-i2v 上拒绝。图像格式:JPEG、JPG、PNG、BMP、WEBP。分辨率:360-2000 像素。文件大小:最大 10MB。
object[]
用于 wan2.7、wan3.0 和 happyhorse-1.x 模型的媒体资产列表。指定用于视频生成的参考素材(图像、音频、视频)。 每个元素包含 type 和 url 字段。 支持的 type 取值因模型而异:
  • wan2.7-i2v: first_frame、last_frame、driving_audio、first_clip
  • wan2.7-r2v: reference_image、reference_video
  • wan2.7-videoedit: video、reference_image
  • wan3.0-video: 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……)。
  • happyhorse-1.x-i2v:仅 first_frame,且恰好 1 个。至少 300x300 像素, JPEG/JPG/PNG/WEBP,最大 20MB,公网 URL 或 data:{MIME_type};base64,… URL。 这些写法不接受 img_url;首帧就放在这里。
  • happyhorse-1.x-r2v:仅 reference_image,1 到 9 张。短边至少 400 像素, 最大 20MB,公网 URL 或 data: URL。reference_video 不是该操作的输入类型。
  • happyhorse-1.x-video-edit:video 上面每个资产「最大 20MB」的数值是合作方(PARTNER)对它最终拿到的图像所设的上限,当资产是公网 URL 时按字面生效,因为这些字节从不经过 Comfy。内联的 data: URL 则确实要经过 Comfy,会更早撞上 更低的传输上限:Comfy Router 的 POST 请求体总量上限为 10 MiB,超出即返回 413,而 base64 会让 载荷膨胀约 4/3,因此单个内联资产一旦超过约 7.5 MiB,就会在上面任何合作方规则生效之前先被拒绝; 请求体里带了多个时还会更早,因为 10 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、OSS 临时 URL,或在上面 media 说明中对应模型条目明确允许时(happyhorse-1.x 的 i2v 与 r2v 写法即如此),使用内联的 data:{MIME_type};base64,... URL。各模型的尺寸与像素下限,以及任何合作方规则生效前就限制内联载荷的 10 MiB Router 请求体上限,均见该说明。
string
反向提示词,用于描述你不希望在视频画面中看到的内容
string
文本提示词。支持中文和英文,长度不超过 800 个字符 (wan3.0-video 最多 20,000 个字符;超出限制的内容会被截断)。 对于带有多个参考视频的 wan2.6-r2v,请按参考视频的顺序使用 ‘character1’、‘character2’ 等来指代主体。 示例:“Character1 sings on the roadside, Character2 dances beside it” 对于 wan3.0-video 参考模式,请使用 ‘Image 1’、‘Video 1’、‘Audio 1’ 等来指代 media 数组中对应顺序的媒体资产。
string[]
仅用于 wan2.6-r2v 模型的参考视频网址。由 1-3 个视频网址组成的数组。 输入限制:
  • 格式:mp4、mov
  • 数量:1-3 个视频
  • 单个视频长度:2-30 秒
  • 单个文件大小:最大 30MB
  • 不能与 audio_url 一起使用 参考时长:单个视频最大 5s,两个视频每个最大 2.5s,三个视频按比例更短。 计费:按实际使用的参考时长计费。
string
视频效果模板名称。可选。当前支持:squish、flying、carousel。使用时,prompt 参数会被忽略。
string
要调用的模型 ID。此组件不约束该参数:Comfy Router 会从 POST /v2/models/wan/{model}{model} 路径段填充它,因此 Router 调用方会省略它。直接通过 v1 调用 POST /proxy/wan/api/v1/services/aigc/video-generation/video-synthesis 时必须提供它,可接受写法的枚举定义在该操作自身的组件 WanVideoGenerationRequest 上。
object
视频处理参数
boolean
默认值:"true"
是否为视频添加音频
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 秒(不支持 15s)
  • wan2.7-i2v、wan2.7-t2v:[2, 15] 区间内的整数
  • wan2.7-r2v、wan2.7-videoedit:[2, 10] 区间内的整数
  • wan3.0-video:无视频输入时为 [2, 30] 区间内的整数;有视频输入时,输入 视频总时长 + 输出视频时长不得超过 30 秒;-1 启用智能时长模式,由模型 选择合适的时长 范围:-130
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-i2v:仅 720P、1080P(不支持 480P)
  • wan2.7 模型(i2v、t2v、r2v、videoedit):720P、1080P(默认 1080P)
  • wan3.0-video、wan3.0-video-prime:480P、720P、1080P(上游默认 1080P) 由于分辨率档位决定计费费率,该代理会拒绝既未提供 resolution 也未提供 size 的视频生成请求。 可选值:480P, 720P, 1080P
integer
随机数种子,用于控制模型生成内容的随机性范围:02147483647
string
默认值:"\"single\""
智能多镜头控制。仅在 prompt_extend 启用时生效。 适用于 wan2.6 和 wan2.7-r2v 模型。
  • single:单镜头视频(默认)
  • multi:多镜头视频 可选值:multisingle
string
视频分辨率,格式为 宽度高度。支持的分辨率因模型而异: 对于 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
boolean
默认值:"false"
是否添加水印标志,水印位于右下角
根据 Router 在 GET /v2/models/wan/happyhorse-1.0-i2v/openapi.json 提供的 schema 生成,该文档也是请求到达提供商之前用于校验调用的同一份文档。

输出

object
必填
string
智能重写后的实际提示词(用于视频任务)
string
带音频生成的 I2V 任务的音频 URL
string
请求失败时的错误码(请求成功时不返回)
string
任务完成时间
string
请求失败的详细信息(请求成功时不返回)
string
原始输入提示词(用于视频任务)
object[]
图像生成任务的任务结果列表
string
智能重写后的实际提示词(如果已启用)
string
图像错误码(部分任务失败时返回)
string
图像错误信息(部分任务失败时返回)
string
原始输入提示词
string
已生成图像的图片网址
string
任务执行时间
string
任务提交时间
string
必填
任务 ID
object
图像生成任务的任务结果统计
integer
失败任务数
integer
成功任务数
integer
任务总数
string
必填
任务状态可能的值:PENDINGRUNNINGSUCCEEDEDFAILEDCANCELEDUNKNOWN
string
已完成的视频生成任务的视频 URL。链接有效期 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 编码的媒体内容也计入其中:参见请求体大小

请求头

身份验证、幂等性、请求 ID、错误分类、重试节奏、消费限额。

使用 Router API

模型发现、验证错误、重试与计费。

限制

Router 目前不支持的功能,以及替代方案。