使用 Comfy Router 调用 Wan 2.5 T2V Preview

Wan 2.5 T2V Preview 的 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-t2v-preview 端点： POST https://api.comfy.org/v2/models/wan/wan2.5-t2v-preview

等待结果
入队并稍后收集

import asyncio
from comfy_sdk import AsyncComfy

# 从环境变量中读取 COMFY_API_KEY。
# SDK 会自动创建幂等键，并在自动重试时复用它。
async def main():
    async with AsyncComfy() as client:
        result = await client.models.run(
            "wan/wan2.5-t2v-preview",
            {
                "input": {
                    "prompt": "a single red maple leaf falling onto still water, slow motion, shallow depth of field",
                },
                "parameters": {
                    "resolution": "720P",
                    "duration": 5,
                },
            },
        )

    print("video:", result["output"]["video_url"])

asyncio.run(main())

import { comfy } from "@comfyorg/sdk";

// 从环境变量中读取 COMFY_API_KEY。
// SDK 会自动创建幂等键，并在自动重试时复用它。
type Result = { output: { video_url: string } };
const result = await comfy.models.run<Result>("wan/wan2.5-t2v-preview", {
  input: {
    prompt: "a single red maple leaf falling onto still water, slow motion, shallow depth of field",
  },
  parameters: {
    resolution: "720P",
    duration: 5,
  },
});
if (result.kind !== "json") throw new Error("expected a JSON result");

console.log("video:", result.data.output.video_url);

curl https://api.comfy.org/v2/models/wan/wan2.5-t2v-preview \
  -H "X-API-Key: $COMFY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{\"input\": {\"prompt\":\"a single red maple leaf falling onto still water, slow motion, shallow depth of field\"}, \"parameters\": {\"resolution\":\"720P\",\"duration\":5}}"

相同的请求体，发送到 POST https://api.comfy.org/v2/models/wan/wan2.5-t2v-preview/requests。运行一经接纳，Router 便立即返回 201 和 request_id；结果就绪后即可收集，无论来自当前进程还是另一个进程。队列投递会详细介绍状态、取消与收集的流程。

import asyncio
from comfy_sdk import AsyncComfy

# 从环境变量中读取 COMFY_API_KEY。
# 每次 submit() 调用都会生成自己的 Idempotency-Key，并在自动重试时复用它。
async def main():
    async with AsyncComfy() as client:
        handle = await client.models.submit(
            "wan/wan2.5-t2v-preview",
            {
                "input": {
                    "prompt": "a single red maple leaf falling onto still water, slow motion, shallow depth of field",
                },
                "parameters": {
                    "resolution": "720P",
                    "duration": 5,
                },
            },
        )
        print("request_id:", handle.request_id)  # 加上模型 ID，就是另一个进程所需的全部信息

        # 轮询直到请求完成，每次等待服务器给出的 Retry-After 时长。
        async for update in handle.iter_events():
            print(update.status, update.queue_position)

        # 提供商自身的载荷，与 models.run() 返回的值相同。
        # 失败或已取消的请求会在此处抛出类型化的 Router 错误。
        result = await handle.get()

    print("video:", result["output"]["video_url"])

asyncio.run(main())

import { comfy } from "@comfyorg/sdk";

// 从环境变量中读取 COMFY_API_KEY。
// 每次 submit() 调用都会生成自己的 Idempotency-Key，并在自动重试时复用它。
type Result = { output: { video_url: string } };
const handle = await comfy.models.submit<Result>("wan/wan2.5-t2v-preview", {
  input: {
    prompt: "a single red maple leaf falling onto still water, slow motion, shallow depth of field",
  },
  parameters: {
    resolution: "720P",
    duration: 5,
  },
});
console.log("requestId:", handle.requestId); // 加上模型 ID，就是另一个进程所需的全部信息

// 轮询直到请求完成，每次等待服务器给出的 Retry-After 时长。
for await (const update of handle.events()) {
  console.log(update.status, update.queuePosition);
}

// 与 models.run() 返回的结果相同。失败或已取消的请求会在此处被拒绝。
const result = await handle.get();
if (result.kind !== "json") throw new Error("expected a JSON result");

console.log("video:", result.data.output.video_url);

# 1. 提交。Router 返回 201，并附带 request_id、status_url、response_url 和 cancel_url。
curl https://api.comfy.org/v2/models/wan/wan2.5-t2v-preview/requests \
  -H "X-API-Key: $COMFY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{\"input\": {\"prompt\":\"a single red maple leaf falling onto still water, slow motion, shallow depth of field\"}, \"parameters\": {\"resolution\":\"720P\",\"duration\":5}}"

# 2. 轮询直到状态为 COMPLETED，每次等待响应中给出的 Retry-After 秒数。
REQUEST_ID="<request_id from the 201 body>"
curl -i https://api.comfy.org/v2/models/wan/wan2.5-t2v-preview/requests/$REQUEST_ID/status \
  -H "X-API-Key: $COMFY_API_KEY"

# 3. 收集。返回 200 和模型的原始输出；仍在运行时则返回 202 和状态响应体。
curl https://api.comfy.org/v2/models/wan/wan2.5-t2v-preview/requests/$REQUEST_ID \
  -H "X-API-Key: $COMFY_API_KEY"

Schema

输入

object

必填

输入基本信息，例如提示词等。

string

音频文件下载网址。支持的格式：mp3 和 wav。不能与 reference_video_urls 一起使用。

string

首帧图像网址或 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。

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，可以是公开网址或 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。至少需要 1 个 reference_image 或 reference_video，且参考图像与参考视频合计最多 5 个。first_frame 和 reference_image：JPEG/JPG/PNG/BMP/WEBP（无 alpha 通道），每边 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 类型在同一请求中互斥。数组顺序决定提示词中资产的参考顺序（Image 1、Video 1、Audio 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/BMP/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：本组件没有为这些拼写枚举任何媒体词汇。 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 形式发送。

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。在这些模型上，没有任何 video、audio、file 或 link 输入接受内联 data: URL。来自合作伙伴自有上传服务的 oss://dashscope-instant 临时 URL，或（在 wan2.7-videoedit 上）Asset Center 的 asset_id，只能针对上传它的那个阿里云账户进行解析；Comfy 使用自己的密钥发起模型调用，且不提供任何上传路由，因此调用方自己的 oss:// URL 或 asset_id 不是受支持的输入。该字段不校验 URL scheme，因此这类值会按原样转发给合作伙伴，而不会在此处被拒绝。有关各模型的大小与像素限制，以及约束内联载荷总量的 100 MiB Router 请求体上限，请参见 media 描述。

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 模型的参考视频 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 秒（不支持 15s）
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 上返回 400（无论是以 resolution 还是以 480P 的 size 形式发送）。可能的值：480P、720P、1080P

integer

随机数种子，用于控制模型生成内容的随机性范围：0 到 2147483647

string

默认值:"\"single\""

智能多镜头控制。仅在启用 prompt_extend 时生效。适用于 wan2.6 和 wan2.7-r2v 模型。

single：单镜头视频（默认）
multi：多镜头视频可能的值：multi、single

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 当同时发送 size 和 resolution 时，由 size 决定计费的档位，而 resolution 仍必须是该代理针对该模型所接受的值。对于分辨率描述中列为不支持 480P 的每个模型，使用 480P 的 size 都会返回 400。

boolean

默认值:"false"

是否添加水印标识，水印位于右下角

本文档根据 Router 在 GET /v2/models/wan/wan2.5-t2v-preview/openapi.json 提供的 schema 生成，该 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

必填

任务状态可能的值：PENDING、RUNNING、SUCCEEDED、FAILED、CANCELED、UNKNOWN

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 之前请先阅读此处。

示例

输入

{
  "input": {
    "prompt": "a single red maple leaf falling onto still water, slow motion, shallow depth of field"
  },
  "parameters": {
    "resolution": "720P",
    "duration": 5
  }
}

输出

{
  "output": {
    "task_id": "0385dc79-5ff8-4d82-bcb6-7c1a9f2e4d60",
    "task_status": "SUCCEEDED",
    "submit_time": "2027-01-01T00:00:00.000Z",
    "scheduled_time": "2027-01-01T00:00:01.000Z",
    "end_time": "2027-01-01T00:01:04.000Z",
    "orig_prompt": "a single red maple leaf falling onto still water, slow motion, shallow depth of field",
    "actual_prompt": "a single red maple leaf falling onto still water, slow motion, shallow depth of field, soft morning light, gentle ripples spreading outward",
    "video_url": "https://.../generated.mp4"
  },
  "request_id": "7574ee8f-38a3-4b1e-9280-11c33ab46e51",
  "usage": {
    "video_count": 1,
    "video_duration": 5,
    "video_ratio": "1280*720"
  }
}

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

使用 Comfy 开发

运行工作流

Comfy Router

Comfy CLI

规范

Demo Apps

使用 Comfy Router 调用 Wan 2.5 T2V Preview

快速开始

Schema

输入

输出

示例

输入

输出

发布前须知

请求头

使用 Router API

限制

​快速开始

​Schema

​输入

​输出

​示例

​输入

​输出

​发布前须知

请求头

使用 Router API

限制

快速开始

Schema

输入

输出

示例

输入

输出

发布前须知