使用 Comfy Router 调用 Wan 2.7 R2V

Wan 2.7 R2V 的 API 参考。Wan 2.7 参考生视频可将参考图像和参考视频中的主体带入新的场景，并在提示词中以 character1、character2 等名称来指代。

快速开始

在你的 Comfy 工作区中创建一个密钥，并将其导出为 COMFY_API_KEY。Python、TypeScript 和 Swift 代码片段使用 Comfy SDK（pip install comfy-sdk、npm install @comfyorg/sdk，以及 ComfySwiftSDK Swift 包）；cURL 代码片段则是通过原始 HTTP 发起的同一调用。 模型 ID： wan/wan2.7-r2v 端点： POST https://api.comfy.org/v2/models/wan/wan2.7-r2v

等待结果
排队并稍后收集

from comfy_sdk import Comfy

# 从环境变量中读取 COMFY_API_KEY。
# SDK 会自动创建一个幂等键，并在自动重试时复用它。
with Comfy() as client:
    result = client.models.run(
        "wan/wan2.7-r2v",
        {
            "input": {
                "prompt": "character1 walks in from the left, turns to the camera and waves, plain orange backdrop",
                "media": [
                    {
                        "type": "reference_image",
                        "url": "https://raw.githubusercontent.com/Comfy-Org/workflow_templates/main/input/pink_robot_front.png",
                    },
                ],
            },
            "parameters": {
                "resolution": "720P",
                "duration": 5,
            },
        },
    )

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

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

// 从环境变量中读取 COMFY_API_KEY。
// SDK 会自动创建一个幂等键，并在自动重试时复用它。
type Result = { output: { video_url: string } };
const result = await comfy.models.run<Result>("wan/wan2.7-r2v", {
  input: {
    prompt: "character1 walks in from the left, turns to the camera and waves, plain orange backdrop",
    media: [
      {
        type: "reference_image",
        url: "https://raw.githubusercontent.com/Comfy-Org/workflow_templates/main/input/pink_robot_front.png",
      },
    ],
  },
  parameters: {
    resolution: "720P",
    duration: 5,
  },
});
if (result.kind !== "json") throw new Error("expected a JSON result");

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

import Foundation
import ComfySwiftSDK

// 从环境变量中读取 COMFY_API_KEY。
// SDK 会为每次调用生成一个幂等键，并在自动重试时复用它。
let client = ComfyCloudClient(apiKey: ProcessInfo.processInfo.environment["COMFY_API_KEY"]!)
let result = try await client.models.run(
    "wan/wan2.7-r2v",
    input: [
        "input": [
            "prompt": "character1 walks in from the left, turns to the camera and waves, plain orange backdrop",
            "media": [
                [
                    "type": "reference_image",
                    "url": "https://raw.githubusercontent.com/Comfy-Org/workflow_templates/main/input/pink_robot_front.png",
                ],
            ],
        ],
        "parameters": [
            "resolution": "720P",
            "duration": 5,
        ],
    ]
)

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

curl https://api.comfy.org/v2/models/wan/wan2.7-r2v \
  -H "X-API-Key: $COMFY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{\"input\": {\"prompt\":\"character1 walks in from the left, turns to the camera and waves, plain orange backdrop\",\"media\":[{\"type\":\"reference_image\",\"url\":\"https://raw.githubusercontent.com/Comfy-Org/workflow_templates/main/input/pink_robot_front.png\"}]}, \"parameters\": {\"resolution\":\"720P\",\"duration\":5}}"

同一个请求体，发送到 POST https://api.comfy.org/v2/models/wan/wan2.7-r2v/requests。一旦运行被接纳，Router 就会返回 201 以及一个 request_id；结果就绪后，可从当前进程或另一个进程收集。队列投递会介绍状态、取消和收集的完整流程。

from comfy_sdk import Comfy

# 从环境变量中读取 COMFY_API_KEY。
# 每次 submit() 调用都会生成自己的 Idempotency-Key，并在自动重试时复用它。
with Comfy() as client:
    handle = client.models.submit(
        "wan/wan2.7-r2v",
        {
            "input": {
                "prompt": "character1 walks in from the left, turns to the camera and waves, plain orange backdrop",
                "media": [
                    {
                        "type": "reference_image",
                        "url": "https://raw.githubusercontent.com/Comfy-Org/workflow_templates/main/input/pink_robot_front.png",
                    },
                ],
            },
            "parameters": {
                "resolution": "720P",
                "duration": 5,
            },
        },
    )
    print("request_id:", handle.request_id)  # 配合模型 ID，另一个进程所需的全部信息

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

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

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

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.7-r2v", {
  input: {
    prompt: "character1 walks in from the left, turns to the camera and waves, plain orange backdrop",
    media: [
      {
        type: "reference_image",
        url: "https://raw.githubusercontent.com/Comfy-Org/workflow_templates/main/input/pink_robot_front.png",
      },
    ],
  },
  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() 返回的结果相同。失败或已取消的请求会在此处 reject。
const result = await handle.get();
if (result.kind !== "json") throw new Error("expected a JSON result");

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

import Foundation
import ComfySwiftSDK

// 从环境变量中读取 COMFY_API_KEY。
// 每次 submit() 调用都会生成自己的 Idempotency-Key，并在自动重试时复用它。
let client = ComfyCloudClient(apiKey: ProcessInfo.processInfo.environment["COMFY_API_KEY"]!)
let handle = try await client.models.submit(
    "wan/wan2.7-r2v",
    input: [
        "input": [
            "prompt": "character1 walks in from the left, turns to the camera and waves, plain orange backdrop",
            "media": [
                [
                    "type": "reference_image",
                    "url": "https://raw.githubusercontent.com/Comfy-Org/workflow_templates/main/input/pink_robot_front.png",
                ],
            ],
        ],
        "parameters": [
            "resolution": "720P",
            "duration": 5,
        ],
    ]
)
print("requestId:", handle.requestId)  // 配合模型 ID，另一个进程所需的全部信息

// 轮询直到请求完成，每次等待服务器指定的 Retry-After 时长。
for try await update in handle.events() {
    print(update.state.rawValue, update.queuePosition.map(String.init) ?? "unknown")
}

// 提供商返回的原始载荷，与 models.run() 返回的值相同。
// 失败或已取消的请求会在此处抛出带类型的 Router 错误。
let result = try await handle.result()

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

# 1. 提交。Router 返回 201，并带有 request_id、status_url、response_url 和 cancel_url。
curl https://api.comfy.org/v2/models/wan/wan2.7-r2v/requests \
  -H "X-API-Key: $COMFY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{\"input\": {\"prompt\":\"character1 walks in from the left, turns to the camera and waves, plain orange backdrop\",\"media\":[{\"type\":\"reference_image\",\"url\":\"https://raw.githubusercontent.com/Comfy-Org/workflow_templates/main/input/pink_robot_front.png\"}]}, \"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.7-r2v/requests/$REQUEST_ID/status \
  -H "X-API-Key: $COMFY_API_KEY"

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

架构

输入

object

必填

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

string

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

string

首帧图像网址或 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 上会被提供商拒绝。图像格式：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 段，总时长 <= 15 秒）、reference_audio（最多 5 段，总时长 <= 15 秒）、file（最多 1 个，不能与 link 同时使用）、link（最多 1 个，不能与 file 同时使用）。reference_*/file/link 类型与 first_frame/last_frame 类型在同一请求中互斥。数组顺序定义了提示词中资产的引用顺序（图像 1、视频 1、音频 1……）。
happyhorse-1.x-i2v：仅 first_frame，且必须正好 1 个。至少 300x300 像素， JPEG/JPG/PNG/WEBP，最大 20MB，可以是公开网址，也可以是 data:{MIME_type};base64,… 网址。这些写法不接受 img_url；首帧在此处传入。
happyhorse-1.x-r2v：仅 reference_image，数量 1 到 9 个。最短边至少 400 像素，最大 20MB，可以是公开网址或 data: 网址。reference_video 不是该操作的输入类型。
happyhorse-1.x-video-edit：video 上面每个资产的“最大 20MB”数值是合作伙伴对其最终得到的图像所设的上限，当资产为公开网址时按字面适用，因为这些字节从不经过 Comfy。内联（INLINE）data: 网址确实要经过 Comfy，因此还要满足一个传输层上限：Comfy Router 的 POST 请求体总量上限为 100 MiB，超出会被返回 413，而 base64 会让载荷膨胀约 4/3，所以单个内联资产只要超过大约 75 MB，就会在触及此处任何合作伙伴规则之前被拒绝。在该体积下，单个资产即便达到合作伙伴自身 20MB 的上限，内联也完全放得下，因此对单个资产而言起约束作用的正是合作伙伴规则。传输层上限则在同时使用多个资产时起作用，因为 100 MiB 的 Router 上限约束的是整个请求，而不是每个元素。任何接近这些上限的内容都应以公开网址发送。

string

必填

媒体资产类型可能的值：first_frame、last_frame、driving_audio、first_clip、reference_image、reference_video、reference_audio、video、file、link

string

必填

媒体文件的网址：公开 HTTP/HTTPS 网址、OSS 临时网址，或者（当上文 media 描述中该模型的条目如此说明时，happyhorse-1.x 的 i2v 和 r2v 写法正属此列）内联的 data:{MIME_type};base64,... 网址。关于各模型的大小与像素下限，以及整体约束内联载荷的 100 MiB Router 请求体上限，请参见该描述。

string

反向提示词，用于描述你不希望在视频画面中看到的内容

string

文本提示词。支持中文和英文，长度不超过 800 个字符（wan3.0-video 最多可达 20,000 个字符；超出限制的内容会被截断）。对于带有多个参考视频的 wan2.6-r2v，请按参考视频的顺序使用 ‘character1’、‘character2’ 等来指代主体。示例：“Character1 在路边唱歌，Character2 在旁边跳舞” 对于 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 同时使用参考时长：单个视频最长 5 秒，两个视频各最长 2.5 秒，三个视频按比例更短。计费：按实际使用的参考时长计算。

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 秒（不支持 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

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

随机种子，用于控制模型生成内容的随机性范围：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

boolean

默认值:"false"

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

本内容由 Router 在 GET /v2/models/wan/wan2.7-r2v/openapi.json 提供的 schema 生成，即在请求到达提供商之前，Router 用于校验调用的同一份文档。

输出

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

失败请求的错误代码，报告在响应封装（envelope）的根层级，而不是 output 下（请求成功时不返回）。

string

失败请求的详细信息，报告在响应封装（envelope）的根层级，而不是 output 下（请求成功时不返回）。在回退到 output.message 之前请先阅读此项。

示例

输入

{
  "input": {
    "prompt": "character1 walks in from the left, turns to the camera and waves, plain orange backdrop",
    "media": [
      {
        "type": "reference_image",
        "url": "https://raw.githubusercontent.com/Comfy-Org/workflow_templates/main/input/pink_robot_front.png"
      }
    ]
  },
  "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": "character1 walks in from the left, turns to the camera and waves, plain orange backdrop",
    "actual_prompt": "character1 walks in from the left, turns to the camera and waves, plain orange backdrop, even studio lighting, steady medium shot",
    "video_url": "https://.../generated.mp4"
  },
  "request_id": "7574ee8f-38a3-4b1e-9280-11c33ab46e51",
  "usage": {
    "SR": 720,
    "duration": 5
  }
}

视频 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.7 R2V

快速开始

架构

输入

输出

示例

输入

输出

发布前须知

请求头

使用 Router API

限制

​快速开始

​架构

​输入

​输出

​示例

​输入

​输出

​发布前须知

请求头

使用 Router API

限制

快速开始

架构

输入

输出

示例

输入

输出

发布前须知