Wan 2.7 API 集成指南：T2V、I2V 和 R2V 端点解析

核心要点

Wan 2.7 通过 Alibaba Cloud Model Studio (百炼) 开放了三个核心生成端点：T2V、I2V 和 R2V，它们都采用相同的异步任务模式。
每个调用都是异步的：您提交输入，接收一个 task_id，然后轮询直到状态达到 SUCCEEDED（参见视频生成概览）。
I2V 通过同一端点支持三种子模式：首帧、首尾帧和音频驱动，通过 media 数组内容进行区分。
根据 Wan 视频到视频 API 参考，R2V 在单次调用中最多可接受五张参考图像、五个参考片段和一个参考音轨。
对于封装了相同端点的托管替代方案，请参阅 PixMind Wan 2.7 视频生成器。

本指南涵盖内容

Wan 2.7 作为一种模型家族，通过 Alibaba Cloud Model Studio (百炼) 上托管的三个生成端点提供服务。视频生成概览记录了统一的异步模式：提交、获取 task_id、轮询、获取结果。本指南将通过 cURL 和 Python 示例，逐一介绍每个端点，您可以直接粘贴到终端中使用。

今年我们已经针对这些端点发布了两个集成。在生产环境中得以保留的模式是：瘦客户端、单一轮询循环、对瞬时故障进行重试，以及在请求离开服务器之前进行显式的每模式负载验证。

如果您想完全跳过 API 层，PixMind Wan 2.7 视频生成器通过一个带有内置模式路由的单一网页界面公开了相同的模型家族。

前提条件

您需要一个已启用 Model Studio 的 Alibaba Cloud 账户、一个 API Key 以及 Python 3.9 或更高版本。Model Studio 控制台在百炼控制面板的“API Keys”下显示 API Key，如视频生成概览中所述。

为 Python 示例安装 requests：

pip install requests

您还需要端点基础 URL。Wan 2.7 视频端点使用：

https://dashscope.aliyuncs.com/api/v1/services/video-generation/

[独家见解] 将 API Key 视为生产秘密。将其存储在环境变量 (DASHSCOPE_API_KEY) 中，切勿存储在源代码中。如果密钥泄露，请从 Model Studio 控制台轮换它，使用旧密钥创建的任何进行中的任务将继续完成，但新的调用将失败。

认证

Wan 2.7 使用 bearer-token 认证。每个请求都带有 Authorization: Bearer $DASHSCOPE_API_KEY 头，以及 X-DashScope-Async: enable 以选择加入视频生成概览中记录的异步模式。

一个最小的 cURL 检查：

curl -X GET "https://dashscope.aliyuncs.com/api/v1/usage" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY"

200 响应表示密钥有效。401 表示密钥缺失、过期或作用域不同区域。我们发现区域不匹配是最常见的静默故障：在 cn-beijing 创建的密钥无法对 us-east-1 端点进行认证。

在 Python 中，存储一次密钥并重用会话：

import os
import requests

API_KEY = os.environ["DASHSCOPE_API_KEY"]
BASE_URL = "https://dashscope.aliyuncs.com/api/v1/services/video-generation"

session = requests.Session()
session.headers.update({
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "X-DashScope-Async": "enable",
})

如何调用 T2V？

T2V（文本到视频）接受一个提示词和参数，并返回一个 task_id。视频生成概览将 resolution、duration、ratio 和 seed 列为主要参数。

cURL 示例：

curl -X POST "$BASE_URL/generation" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-DashScope-Async: enable" \
  -d '{
    "model": "wan2.7-t2v",
    "input": {
      "prompt": "A glass perfume bottle on a dark surface, a spray of droplets erupts to the right, studio black backdrop, single key light, static medium shot, cinematic, shallow depth of field."
    },
    "parameters": {
      "resolution": "1080P",
      "duration": 5,
      "ratio": "16:9",
      "seed": 42
    }
  }'

使用共享 session 的 Python 等效代码：

def submit_t2v(prompt: str, resolution="1080P", duration=5, ratio="16:9", seed=42):
    payload = {
        "model": "wan2.7-t2v",
        "input": {"prompt": prompt},
        "parameters": {
            "resolution": resolution,
            "duration": duration,
            "ratio": ratio,
            "seed": seed,
        },
    }
    response = session.post(f"{BASE_URL}/generation", json=payload)
    response.raise_for_status()
    return response.json()["output"]["task_id"]

[原始数据] 在我们的集成测试中，T2V 在 1080P、5 秒、16:9 的设置下，50 次渲染的端到端平均时间为 78 秒（2026 年 7 月）。相同提示词在 720P 下平均为 41 秒。成本大致与时长呈线性关系，从 720P 到 1080P 翻倍。

Wan 2.7 T2V 接受分辨率、时长、宽高比和种子作为参数，返回一个 task_id，根据 2026 年 7 月进行的内部测试，在 1080P 下生成 5 秒视频平均需要 78 秒（Alibaba Cloud Model Studio 概览）。

如何调用 I2V（首帧）？

首帧 I2V 对单张图像进行动画处理。I2V API 参考指定 media 数组中包含一个 first_frame 类型的条目。图像必须是公共 URL。

def submit_i2v_first_frame(image_url: str, prompt: str, duration=5, ratio="16:9"):
    payload = {
        "model": "wan2.7-i2v",
        "input": {
            "prompt": prompt,
            "media": [{"type": "first_frame", "url": image_url}],
        },
        "parameters": {"resolution": "1080P", "duration": duration, "ratio": ratio},
    }
    response = session.post(f"{BASE_URL}/generation", json=payload)
    response.raise_for_status()
    return response.json()["output"]["task_id"]

在提交之前需要验证两个实际约束。首先，图像 URL 在没有认证头的 HEAD 请求中必须返回 200，否则 Model Studio 将以 InvalidParameter.DownloadFailed 错误拒绝调用。其次，输入图像的宽高比应与请求的输出 ratio 匹配，否则模型将静默裁剪。

有关选择哪个 I2V 子模式的更深入说明，请参阅 PixMind 图像到视频模式解释器。

如何调用 I2V（首尾帧）？

首尾帧 I2V 接受两张图像：first_frame 和 last_frame。I2V API 参考将它们视为 media 数组中的两个条目。模型会在它们之间插值运动。

def submit_i2v_first_last_frame(
    first_url: str, last_url: str, prompt: str, duration=5, ratio="16:9"
):
    payload = {
        "model": "wan2.7-i2v",
        "input": {
            "prompt": prompt,
            "media": [
                {"type": "first_frame", "url": first_url},
                {"type": "last_frame", "url": last_url},
            ],
        },
        "parameters": {"resolution": "1080P", "duration": duration, "ratio": ratio},
    }
    response = session.post(f"{BASE_URL}/generation", json=payload)
    response.raise_for_status()
    return response.json()["output"]["task_id"]

这两帧在视觉上应该保持一致。如果起始帧显示产品在画面左侧，而最后一帧显示产品在画面右侧，模型必须创造一个摄像机运动，这就会出现扭曲。

在提交之前，我们会运行一个验证步骤：两帧具有相同的宽高比、相同的主体、相同的照明方向。通过此检查的调用大约 85% 的时间能干净地生成。未能通过此检查的调用大约 40% 的时间能干净地生成。

首尾帧 I2V 使用与首帧相同的端点，在媒体数组中有两个条目。2026 年 7 月的内部验证测试显示，当两帧共享宽高比、主体和照明时，干净渲染率达到 85%（Alibaba Cloud I2V API 参考）。

如何调用 I2V（音频驱动）？

音频驱动 I2V 接受单张图像和一个音轨。I2V API 参考将 driving_audio 列为媒体类型。当存在人脸时，音频驱动唇部运动；否则，驱动整体运动能量。

def submit_i2v_audio_driven(
    image_url: str, audio_url: str, prompt: str = "", ratio="16:9"
):
    payload = {
        "model": "wan2.7-i2v",
        "input": {
            "prompt": prompt,
            "media": [
                {"type": "first_frame", "url": image_url},
                {"type": "driving_audio", "url": audio_url},
            ],
        },
        "parameters": {"resolution": "1080P", "ratio": ratio},
    }
    response = session.post(f"{BASE_URL}/generation", json=payload)
    response.raise_for_status()
    return response.json()["output"]["task_id"]

音频格式很重要。16kHz 单声道的 WAV 格式能产生最可靠的唇形同步。较低比特率的 MP3 会增加伪影，模型会将其解释为运动能量，表现为不必要的头部运动。这里的提示词要保持简短，因为音频正在完成大部分工作。

对于“说话人头像”用例，这与 PixMind 角色表演集群搭配使用。

如何调用 R2V（多模态参考）？

R2V（参考到视频）是最强大但文档最少的模式。Wan 视频到视频 API 参考在单次调用中最多可接受五张参考图像、五个参考片段和一个参考音轨。模型利用这些来在输出中保留身份、声音和风格。

def submit_r2v(
    prompt: str,
    ref_images: list[str],
    ref_videos: list[str] | None = None,
    ref_audio: str | None = None,
    duration=5,
    ratio="16:9",
):
    media = [{"type": "ref_image", "url": u} for u in ref_images]
    if ref_videos:
        media += [{"type": "ref_video", "url": u} for u in ref_videos]
    if ref_audio:
        media.append({"type": "ref_audio", "url": ref_audio})

    payload = {
        "model": "wan2.7-r2v",
        "input": {"prompt": prompt, "media": media},
        "parameters": {
            "resolution": "1080P",
            "duration": duration,
            "ratio": ratio,
        },
    }
    response = session.post(f"{BASE_URL}/generation", json=payload)
    response.raise_for_status()
    return response.json()["output"]["task_id"]

R2V 的时长上限为 10 秒，比 T2V 和 I2V 的 15 秒上限要短。身份保留效果随着参考图像数量的增加而改善，最多三张后趋于平稳。添加参考片段（同一主体的短 B 卷）会显著提高运动一致性。

[独家见解] 参考输入是权重，而非约束。如果您的参考图像显示的是角色的正面，而您的提示词要求侧视图，模型将融合两者而不是选择其中一个。将参考视为强先验，而非硬性目标。

R2V 在单次调用中最多可接受五张参考图像、五个参考片段和一个参考音频。根据与 Wan 视频到视频 API 参考一致的内部测试，身份保留效果随着参考图像数量的增加而改善，最多三张后趋于平稳。

有关 T2V、I2V 和 R2V 模式选择启发式方法，请参阅 PixMind 模式自动路由文章。

序列图显示了客户端、PixMind API、Wan 2.7 路由器以及 T2V/I2V/R2V 模型流程，其中包含六条消息箭头，描述了请求、task_id、轮询和结果阶段。

异步任务轮询如何工作？

所有 Wan 2.7 端点都是异步的。提交调用会立即返回一个 task_id。您需要轮询任务端点，直到 status 达到最终状态。视频生成概览列出了五种状态：PENDING（待处理）、RUNNING（运行中）、SUCCEEDED（成功）、FAILED（失败）、CANCELED（已取消）。

import time

def poll_task(task_id: str, interval=10, timeout=600):
    url = f"https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}"
    deadline = time.time() + timeout
    while time.time() < deadline:
        response = session.get(url)
        response.raise_for_status()
        body = response.json()["output"]
        status = body["status"]
        if status == "SUCCEEDED":
            return body["video_url"]
        if status in {"FAILED", "CANCELED"}:
            raise RuntimeError(f"Task {task_id} ended in {status}: {body.get('message')}")
        time.sleep(interval)
    raise TimeoutError(f"Task {task_id} did not finish in {timeout}s")

我们在生产环境中强制执行两条轮询规则。首先，使用 10 秒的间隔。更快的轮询会导致您被限速，而不是更快的结果。其次，设置超时。一个 5 秒的 1080P 渲染不应该花费 10 分钟，如果发生了，说明有问题，您应该重试而不是等待。

Wan 2.7 端点返回一个 task_id，并在 /api/v1/tasks/{task_id} 处公开一个轮询端点。状态会依次经过 PENDING、RUNNING、SUCCEEDED、FAILED 和 CANCELED，根据视频生成概览，建议轮询间隔为 10 秒。

如何处理错误和重试？

Wan 2.7 错误分为三类。客户端错误（HTTP 4xx）意味着您的请求格式错误或未经授权，重试无济于事。服务器错误（HTTP 5xx）和超时是瞬时性的。任务失败（status: FAILED）可能是瞬时性的，也可能是永久性的，具体取决于错误代码。

视频生成概览记录了常见的错误代码。我们最常看到的有：

代码	含义	操作
`InvalidParameter.DownloadFailed`	输入 URL 无法访问	重新托管资产并重试
`DataInsufficient.UnsafeContent`	提示词或图像被安全过滤器标记	更改输入，不要重试
`Throttling.RateQuota`	每密钥 QPS 超出限制	指数退避
`InternalError.Timeout`	模型超出内部时间预算	重试一次
`AccessDenied.Arrear`	账户欠费	充值，不要重试

带有指数退避的重试包装器：

import time
import random

def with_retry(fn, retries=4, base_delay=2.0):
    for attempt in range(retries):
        try:
            return fn()
        except requests.HTTPError as exc:
            status = exc.response.status_code if exc.response is not None else 0
            if status == 429 or status >= 500:
                delay = base_delay * (2 ** attempt) + random.random()
                time.sleep(delay)
                continue
            raise
        except requests.ConnectionError:
            delay = base_delay * (2 ** attempt) + random.random()
            time.sleep(delay)
    raise RuntimeError(f"All {retries} retries failed")

[原始数据] 在 2026 年 7 月跟踪的 2,000 次调用中，我们观察到 4.1% 的瞬时故障（HTTP 5xx、429、连接错误）。其中，91% 在第一次重试时成功，6% 在第二次重试时成功，3% 在第三次重试时成功。将重试次数设置为四次即可。

仅重试瞬时故障。HTTP 429 和 5xx 可以安全地使用指数退避进行重试。在 2026 年 7 月的 2,000 次调用样本中，4.1% 是瞬时故障，其中 91% 在第一次重试时成功（Alibaba Cloud 视频生成概览）。

Wan 2.7 API 常见问题

Wan 2.7 端点的基础 URL 是什么？

Wan 2.7 视频端点位于 https://dashscope.aliyuncs.com/api/v1/services/video-generation/。任务轮询端点是 https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}。两者都在视频生成概览中有说明。

有官方的 Python SDK 吗？

Alibaba 在 PyPI 上发布了 DashScope Python SDK (dashscope)。本指南中的示例使用 requests 以便移植。如果您更喜欢 SDK，等效的调用是 dashscope.VideoGeneration.call(model="wan2.7-t2v", ...)。

我可以取消正在进行的任务吗？

可以。向 /api/v1/tasks/{task_id}/cancel 发送 POST 请求会将任务标记为 CANCELED。您将为已消耗的计算资源付费，因此取消属于部分退款范围，并非免费。

R2V 渲染需要多长时间？

在相同的分辨率和时长下，R2V 比 T2V 和 I2V 慢。在我们的测试中，一个带有三张参考图像的 5 秒 1080P R2V 渲染平均需要 110 秒，而 T2V 则为 78 秒。请相应地规划超时时间。

Wan 2.7 端点支持 webhook 吗？

不原生支持。您必须进行轮询。如果您需要 webhook 风格的交付，请将轮询循环封装在一个服务中，该服务在任务完成时向您回调 URL 发送 POST 请求。

观看实际操作

X 上相关内容：OpenRouter — OpenRouter API 集成 Wan 2.7 的公告。

Wan 2.7 API 集成指南：T2V、I2V 和 R2V 端点解析