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/ に保存します。
• トラブルシューティング用に、エンドツーエンドの実行ログを少なくとも 1 つ残してください。

前提条件

• SDK をインストールします（venv の使用を推奨します）。

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

• 環境に DASHSCOPE_API_KEY を設定するか、~/.alibabacloud/credentials に dashscope_api_key を追加します。

重要なモデル名

• wan2.7-i2v — 始点フレーム、始点＋終点フレーム、動画の続きの生成、音声駆動型生成に対応

機能

機能	説明	必須のメディアタイプ
始点フレームからの動画生成	1 枚の画像から動画を生成	first_frame
始点＋終点フレーム	2 枚の画像の間を補間して動画を生成	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 generated」ウォーターマークを追加（デフォルト：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～30 秒
• 最大サイズ：15MB
• duration の値を超える場合は自動的に切り詰められます

動画（first_clip）：

• 形式：mp4、mov
• 長さ：2～10 秒
• 解像度：各辺 [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 が 2 つ）を渡さないでください。
• 動画 URL は 24 時間後に有効期限が切れるため、すぐにダウンロードして保存してください。
• 動画編集にこの API を使用しないでください。代わりに aliyun-wan-videoedit を使用してください。

ワークフロー

1. ユーザーの意図を確認します：最初のフレーム、最初と最後のフレーム、動画の続きを生成、または音声駆動のいずれかです。
2. 正しい型と有効な URL を指定してメディア配列を準備します。
3. 非同期タスクを作成し、結果をポーリングします。
4. URL の有効期限が切れる前に、生成された動画をダウンロードして保存します。

参考資料

• HTTP API の詳細については、references/api_reference.md を参照してください。
• ソースリンクについては、references/sources.md を参照してください。