aliyun-wan-i2v

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Wan 2.7 Image-to-Video

Wan 2.7 图生视频

Validation

验证

bash

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

Pass criteria: command exits 0 and

output/aliyun-wan-i2v/validate.txt

is generated.

bash

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

文件。

Output And Evidence

输出与证据

Save task IDs, polling responses, and final video URLs to
```
output/aliyun-wan-i2v/
```
.
Keep at least one end-to-end run log for troubleshooting.

将任务ID、轮询响应和最终视频URL保存至
```
output/aliyun-wan-i2v/
```
目录。
保留至少一份端到端运行日志用于故障排查。

Prerequisites

前置条件

Install SDK (recommended in a venv):

bash

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

Set

DASHSCOPE_API_KEY

in your environment, or add

dashscope_api_key

~/.alibabacloud/credentials

安装SDK（建议在虚拟环境中进行）：

bash

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

在环境变量中设置

DASHSCOPE_API_KEY

，或在

~/.alibabacloud/credentials

中添加

dashscope_api_key

。

Critical model names

关键模型名称

```
wan2.7-i2v
```
— supports first-frame, first+last frame, video continuation, and audio-driven generation

```
wan2.7-i2v
```
— 支持首帧生成、首尾帧插值、视频续播和音频驱动生成

Capabilities

功能特性

Capability	Description	Required media types
First-frame video	Generate video from a single image	`first_frame`
First+last frame	Interpolate video between two images	`first_frame` + `last_frame`
Video continuation	Extend an existing video clip	`first_clip`
Audio-driven	Drive video with audio (lip-sync, rhythm)	`first_frame` + `driving_audio`

功能	描述	所需媒体类型
首帧视频生成	从单张图像生成视频	`first_frame`
首尾帧插值	在两张图像之间生成过渡视频	`first_frame` + `last_frame`
视频续播	扩展现有视频片段	`first_clip`
音频驱动	用音频驱动视频生成（唇形同步、节奏匹配）	`first_frame` + `driving_audio`

API endpoint (async only)

API端点（仅支持异步）

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

Required headers:

Authorization: Bearer $DASHSCOPE_API_KEY

```
Content-Type: application/json
```
```
X-DashScope-Async: enable
```

Singapore endpoint: replace

dashscope.aliyuncs.com

with

dashscope-intl.aliyuncs.com

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

。

Normalized interface

标准化接口

Request

请求参数

```
prompt
```
(string, optional) — up to 5000 characters, describes desired video content
```
negative_prompt
```
(string, optional) — up to 500 characters
```
media
```
(array, required) — media objects with
```
type
```
and
```
url
```
fields:
- ```
type
```
  :
```
first_frame
```
  |
```
last_frame
```
  |
```
driving_audio
```
  |
```
first_clip
```
- ```
url
```
  : public URL (HTTP/HTTPS) or OSS temporary URL
```
resolution
```
(string, optional) —
```
720P
```
or
```
1080P
```
(default:
```
1080P
```
)
```
duration
```
(integer, optional) — video length in seconds, range [2, 15] (default: 5)
```
prompt_extend
```
(boolean, optional) — AI prompt rewriting (default: true)
```
watermark
```
(boolean, optional) — add "AI generated" watermark (default: false)
```
seed
```
(integer, optional) — range [0, 2147483647]

```
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]

Media input limits

媒体输入限制

Images (first_frame, last_frame):

Formats: JPEG, JPG, PNG (no transparency), BMP, WEBP
Resolution: [240, 8000] pixels per side
Aspect ratio: 1:8 to 8:1
Max size: 20MB

Audio (driving_audio):

Formats: wav, mp3
Duration: 2-30s
Max size: 15MB
Auto-truncated to
```
duration
```
value if longer

Video (first_clip):

Formats: mp4, mov
Duration: 2-10s
Resolution: [240, 4096] pixels per side
Aspect ratio: 1:8 to 8:1
Max size: 100MB

图像（first_frame、last_frame）：

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

音频（driving_audio）：

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

视频（first_clip）：

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

Response (task creation)

响应（任务创建）

```
output.task_id
```
(string) — use for polling, valid 24 hours
```
output.task_status
```
(string) — PENDING | RUNNING | SUCCEEDED | FAILED | CANCELED
```
request_id
```
(string)

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

Response (task result)

响应（任务结果）

```
output.video_url
```
(string) — generated video URL
```
output.orig_prompt
```
(string) — original prompt
```
output.actual_prompt
```
(string) — rewritten prompt (if prompt_extend enabled)
```
usage.video_count
```
(integer)
```
usage.video_duration
```
(integer) — duration in seconds

```
output.video_url
```
（字符串）—— 生成的视频URL
```
output.orig_prompt
```
（字符串）—— 原始提示词
```
output.actual_prompt
```
（字符串）—— 重写后的提示词（若开启prompt_extend）
```
usage.video_count
```
（整数）
```
usage.video_duration
```
（整数）—— 视频时长（秒）

Quick start (Python + HTTP)

快速开始（Python + HTTP）

python

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)

python

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:
    """创建图生视频任务并返回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:
    """轮询直到任务完成，返回最终响应。"""
    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)

Media combination examples

媒体组合示例

python

undefined

python

undefined

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"}]

undefined

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

undefined

Error handling

错误处理

Error	Likely cause	Action
401/403	Missing or invalid `DASHSCOPE_API_KEY`	Check env var or credentials file
400 `InvalidParameter`	Unsupported resolution, bad duration, missing media	Validate parameters
"does not support synchronous calls"	Missing `X-DashScope-Async: enable` header	Add required header
429	Rate limit or quota	Retry with backoff

错误	可能原因	处理措施
401/403	`DASHSCOPE_API_KEY` 缺失或无效	检查环境变量或凭据文件
400 `InvalidParameter`	不支持的分辨率、无效时长、缺失媒体	验证参数合法性
"does not support synchronous calls"	缺少 `X-DashScope-Async: enable` 请求头	添加必填请求头
429	速率限制或配额不足	退避重试

Output location

输出位置

Default output:
```
output/aliyun-wan-i2v/videos/
```
Override base dir with
```
OUTPUT_DIR
```
.

默认输出目录：
```
output/aliyun-wan-i2v/videos/
```
可通过
```
OUTPUT_DIR
```
环境变量覆盖基础目录。

Anti-patterns

反模式

Do not use model names other than
```
wan2.7-i2v
```
.
Do not call this API synchronously — async header is required.
Do not pass duplicate media types (e.g., two
```
first_frame
```
entries).
Video URLs expire after 24 hours; download and persist immediately.
Do not use this API for video editing — use
```
aliyun-wan-videoedit
```
instead.

请勿使用
```
wan2.7-i2v
```
以外的模型名称。
请勿同步调用此API —— 必须添加异步请求头。
请勿传入重复的媒体类型（例如两个
```
first_frame
```
条目）。
视频URL有效期为24小时；请立即下载并持久化保存。
请勿使用此API进行视频编辑 —— 请使用
```
aliyun-wan-videoedit
```
。

Workflow

工作流程

Confirm user intent: first-frame, first+last frame, video continuation, or audio-driven.
Prepare media array with correct types and valid URLs.
Create async task and poll for results.
Download and save generated video before URL expiration.

确认用户需求：首帧生成、首尾帧插值、视频续播或音频驱动。
准备包含正确类型和有效URL的媒体数组。
创建异步任务并轮询结果。
在URL过期前下载并保存生成的视频。

References

参考资料

See
```
references/api_reference.md
```
for full HTTP API details.
See
```
references/sources.md
```
for source links.

完整HTTP API详情请查看
```
references/api_reference.md
```
。
源码链接请查看
```
references/sources.md
```
。