aliyun-wan-i2v

Wan 2.7 图生视频

验证

mkdir -p output/aliyun-wan-i2v
python -m py_compile skills/ai/video/aliyun-wan-i2v/scripts/generate_i2v.py && echo "py_compile_ok" > output/aliyun-wan-i2v/validate.txt

通过标准：命令以状态码 0 退出，并生成 output/aliyun-wan-i2v/validate.txt。

输出与证据

• 将任务 ID、轮询响应和最终视频 URL 保存到 output/aliyun-wan-i2v/。
• 至少保留一份端到端运行日志，以便排查问题。

前置条件

• 安装 SDK（建议在 venv 中安装）：

python3 -m venv .venv
. .venv/bin/activate
python -m pip install dashscope

• 在环境中设置 DASHSCOPE_API_KEY，或将 dashscope_api_key 添加到 ~/.alibabacloud/credentials。

关键模型名称

• wan2.7-i2v — 支持首帧、首帧 + 尾帧、视频续接和音频驱动生成

功能

功能	描述	所需媒体类型
首帧视频	根据单张图像生成视频	first_frame
首帧 + 尾帧	在两张图像之间插值生成视频	first_frame + last_frame
视频续接	延长现有视频片段	first_clip
音频驱动	使用音频驱动视频（口型同步、节奏）	first_frame + driving_audio

API 端点（仅支持异步）

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

必需请求头：

• Authorization: Bearer $DASHSCOPE_API_KEY
• Content-Type: application/json
• X-DashScope-Async: enable

新加坡端点：将 dashscope.aliyuncs.com 替换为 dashscope-intl.aliyuncs.com。

规范化接口

请求

• prompt（字符串，可选）— 最多 5000 个字符，用于描述期望的视频内容
• negative_prompt（字符串，可选）— 最多 500 个字符
• media（数组，必需）— 包含 type 和 url 字段的媒体对象：
  • type：first_frame | last_frame | driving_audio | first_clip
  • url：公开 URL（HTTP/HTTPS）或 OSS 临时 URL
• resolution（字符串，可选）— 720P 或 1080P（默认：1080P）
• duration（整数，可选）— 视频时长，单位为秒，范围 [2, 15]（默认：5）
• prompt_extend（布尔值，可选）— AI 提示词改写（默认：true）
• watermark（布尔值，可选）— 添加“AI 生成”水印（默认：false）
• seed（整数，可选）— 范围 [0, 2147483647]

媒体输入限制

图像（first_frame、last_frame）：

• 格式：JPEG、JPG、PNG（不支持透明度）、BMP、WEBP
• 分辨率：每边 [240, 8000] 像素
• 宽高比：1:8 至 8:1
• 最大大小：20MB

音频（driving_audio）：

• 格式：wav、mp3
• 时长：2-30s
• 最大大小：15MB
• 如果时长超过 duration 值，将自动截断

视频（first_clip）：

• 格式：mp4、mov
• 时长：2-10s
• 分辨率：每边 [240, 4096] 像素
• 宽高比：1:8 至 8:1
• 最大大小：100MB

响应（创建任务）

• output.task_id（字符串）— 用于轮询，有效期为 24 小时
• output.task_status（字符串）— PENDING | RUNNING | SUCCEEDED | FAILED | CANCELED
• request_id（字符串）

响应（任务结果）

• output.video_url（字符串）— 生成的视频 URL
• output.orig_prompt（字符串）— 原始提示词
• output.actual_prompt（字符串）— 改写后的提示词（启用 prompt_extend 时）
• usage.video_count（整数）
• usage.video_duration（整数）— 时长，单位为秒

快速开始（Python + HTTP）

import os
import json
import time
import requests

API_KEY = os.getenv("DASHSCOPE_API_KEY")
BASE_URL = "https://dashscope.aliyuncs.com/api/v1"

def create_i2v_task(req: dict) -> str:
    """Create an image-to-video task and return task_id."""
    payload = {
        "model": "wan2.7-i2v",
        "input": {
            "prompt": req.get("prompt", ""),
            "media": req["media"],
        },
        "parameters": {
            "resolution": req.get("resolution", "1080P"),
            "duration": req.get("duration", 5),
            "prompt_extend": req.get("prompt_extend", True),
            "watermark": req.get("watermark", False),
        },
    }
    if req.get("negative_prompt"):
        payload["input"]["negative_prompt"] = req["negative_prompt"]
    if req.get("seed") is not None:
        payload["parameters"]["seed"] = req["seed"]

    resp = requests.post(
        f"{BASE_URL}/services/aigc/video-generation/video-synthesis",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
            "X-DashScope-Async": "enable",
        },
        json=payload,
    )
    resp.raise_for_status()
    data = resp.json()
    return data["output"]["task_id"]


def poll_task(task_id: str, interval: int = 15) -> dict:
    """Poll until task completes. Returns final response."""
    while True:
        resp = requests.get(
            f"{BASE_URL}/tasks/{task_id}",
            headers={"Authorization": f"Bearer {API_KEY}"},
        )
        resp.raise_for_status()
        data = resp.json()
        status = data["output"]["task_status"]
        if status in ("SUCCEEDED", "FAILED", "CANCELED"):
            return data
        time.sleep(interval)

媒体组合示例

# First-frame only
media = [{"type": "first_frame", "url": "https://example.com/image.jpg"}]

# First + last frame interpolation
media = [
    {"type": "first_frame", "url": "https://example.com/start.jpg"},
    {"type": "last_frame", "url": "https://example.com/end.jpg"},
]

# Audio-driven from first frame
media = [
    {"type": "first_frame", "url": "https://example.com/face.jpg"},
    {"type": "driving_audio", "url": "https://example.com/speech.mp3"},
]

# Video continuation
media = [{"type": "first_clip", "url": "https://example.com/clip.mp4"}]

错误处理

错误	可能原因	操作
401/403	缺少或无效的 DASHSCOPE_API_KEY	检查环境变量或凭据文件
400 InvalidParameter	不支持的分辨率、无效的时长、缺少媒体	验证参数
“does not support synchronous calls”	缺少 X-DashScope-Async: enable 请求头	添加必需请求头
429	速率限制或配额不足	采用退避策略重试

输出位置

• 默认输出：output/aliyun-wan-i2v/videos/
• 使用 OUTPUT_DIR 覆盖基础目录。

反模式

• 不要使用 wan2.7-i2v 以外的模型名称。
• 不要同步调用此 API — 必须使用异步请求头。
• 不要传入重复的媒体类型（例如，两个 first_frame 条目）。
• 视频 URL 会在 24 小时后过期；请立即下载并持久化保存。
• 不要将此 API 用于视频编辑 — 请改用 aliyun-wan-videoedit。

工作流

1. 确认用户意图：首帧、首帧 + 末帧、视频续写或音频驱动。
2. 准备媒体数组，确保类型正确且 URL 有效。
3. 创建异步任务并轮询结果。
4. 在 URL 过期前下载并保存生成的视频。

参考资料

• 完整的 HTTP API 详情请参阅 references/api_reference.md。
• 源链接请参阅 references/sources.md。