aliyun-vidu-video

Vidu 動画生成

検証

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

合格基準：コマンドが終了コード 0 で終了し、output/aliyun-vidu-video/validate.txt が生成されます。

出力とエビデンス

• タスク ID、ポーリング応答、最終的な動画 URL を output/aliyun-vidu-video/ に保存します。
• トラブルシューティング用に、エンドツーエンドの実行ログを少なくとも 1 つ保持します。

前提条件

• 環境に DASHSCOPE_API_KEY を設定します（北京リージョンのキーが必要です）。
• リージョン：中国本土（北京）のみ。モデル、エンドポイント URL、API キーは同じリージョンに属している必要があります。
• 初回使用前に Alibaba Cloud Model Studio コンソールで Vidu モデルを有効にします。

重要なモデル名

テキストから動画

• vidu/viduq3-pro_text2video
• vidu/viduq3-turbo_text2video
• vidu/viduq2_text2video

画像から動画（最初のフレーム）

• vidu/viduq3-pro_img2video
• vidu/viduq3-turbo_img2video
• vidu/viduq2-pro_img2video
• vidu/viduq2-turbo_img2video

キーフレームから動画（最初と最後のフレーム）

• vidu/viduq3-pro_start-end2video
• vidu/viduq3-turbo_start-end2video
• vidu/viduq2-pro_start-end2video
• vidu/viduq2-turbo_start-end2video

参照画像から動画

• vidu/viduq2_reference2video
• vidu/viduq2-pro_reference2video

機能

機能	説明	モデルのサフィックス	必須入力
テキストから動画	テキストプロンプトのみから動画を生成	_text2video	prompt
画像から動画	1 枚の画像と任意のプロンプトから動画を生成	_img2video	media[image]
キーフレームから動画	最初と最後のフレーム画像の間を補間して動画を生成	_start-end2video	media[image x2] + prompt
参照画像から動画	参照する被写体をプロンプトで指定したシーンに組み込む	_reference2video	media[image 1-7] + prompt

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

正規化されたインターフェース

リクエスト

• model（string、必須）-- 上記のモデル名のいずれか
• input.prompt（string）-- 最大 5000 文字。希望する動画の内容を記述します
  • テキストから動画、キーフレーム、参照モードでは必須です
  • 画像から動画では任意です
• input.media（array）-- type と url フィールドを持つメディアオブジェクト（テキストから動画では使用しません）
  • type：image または video
  • url：公開 URL（HTTP/HTTPS）
• parameters.resolution（string、任意）-- 540P、720P（デフォルト）、または 1080P
• parameters.size（string、任意）-- ピクセル寸法 width*height（例：1280*720）。値は解像度の区分によって異なります。テキストから動画と参照画像から動画では、サイズを明示的に指定できます。
• parameters.duration（integer、任意）-- 動画の長さ（秒）
  • Q3 モデル： [1, 16]、デフォルトは 5
  • Q2 モデル： [1, 10]、デフォルトは 5
• parameters.audio（boolean、任意）-- 音声トラックを生成します（Q3 モデルのみ、デフォルトは false）
• parameters.watermark（boolean、任意）-- 「AI generated」のウォーターマークを追加します（デフォルトは false）
• parameters.seed（integer、任意）-- 範囲 [0, 2147483647]

解像度の区分ごとのサイズ（テキストから動画）

解像度	アスペクト比	サイズ（width*height）
540P	16:9	960*528
540P	9:16	528*960
540P	1:1	720*720
540P	4:3	816*608
540P	3:4	608*816
720P	16:9	1280*720
720P	9:16	720*1280
720P	1:1	960*960
720P	4:3	1104*816
720P	3:4	816*1104
1080P	16:9	1920*1080
1080P	9:16	1080*1920
1080P	1:1	1440*1440
1080P	4:3	1674*1238
1080P	3:4	1238*1674

解像度ティア別のサイズ（参照動画生成）

解像度	アスペクト比	サイズ（幅*高さ）
540P	16:9	960*540
540P	9:16	540*960
540P	1:1	540*540
540P	4:3	720*540
540P	3:4	540*720
720P	16:9	1280*720
720P	9:16	720*1280
720P	1:1	720*720
720P	4:3	960*720
720P	3:4	720*960
1080P	16:9	1920*1080
1080P	9:16	1080*1920
1080P	1:1	1080*1080
1080P	4:3	1440*1080
1080P	3:4	1080*1440

メディア入力の制限

画像（type=image）：

• 形式：JPG、PNG、WEBP
• アスペクト比：1:4～4:1
• 最大サイズ：50MB

動画（type=video、参照動画生成のみ）：

• 形式：mp4、avi、mov
• 解像度：最小128x128ピクセル
• アスペクト比：1:4～4:1
• 長さ：1～5秒
• 最大サイズ：50MB

レスポンス（タスク作成時）

• output.task_id（string）-- ポーリングに使用します。有効期間は24時間です
• output.task_status（string）-- PENDING | RUNNING | SUCCEEDED | FAILED | CANCELED | UNKNOWN
• request_id（string）

レスポンス（タスク結果）

• output.video_url（string）-- 生成された動画のURL（MP4、H.264）。有効期間は24時間です
• output.orig_prompt（string）-- 元のプロンプト
• usage.duration（integer）-- 課金対象となる動画の長さ（秒）
• usage.output_video_duration（integer）-- 実際の出力時間
• usage.size（string）-- 出力解像度
• usage.fps（integer）-- フレームレート（24）
• usage.audio（boolean）-- 音声が生成されたかどうか
• usage.SR（string）-- 解像度ティア

クイックスタート（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_vidu_task(req: dict) -> str:
    """Create a Vidu video generation task and return task_id."""
    payload = {
        "model": req["model"],
        "input": {},
        "parameters": {
            "resolution": req.get("resolution", "720P"),
            "duration": req.get("duration", 5),
        },
    }
    if req.get("prompt"):
        payload["input"]["prompt"] = req["prompt"]
    if req.get("media"):
        payload["input"]["media"] = req["media"]
    if req.get("size"):
        payload["parameters"]["size"] = req["size"]
    if req.get("audio") is not None:
        payload["parameters"]["audio"] = req["audio"]
    if req.get("watermark") is not None:
        payload["parameters"]["watermark"] = req["watermark"]
    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)

モード別の例

# Text-to-video
task_id = create_vidu_task({
    "model": "vidu/viduq3-turbo_text2video",
    "prompt": "A cat running under moonlight",
    "resolution": "540P",
    "size": "960*528",
    "duration": 5,
})

# Image-to-video (first frame)
task_id = create_vidu_task({
    "model": "vidu/viduq3-pro_img2video",
    "prompt": "Camera slowly pans upward",
    "media": [{"type": "image", "url": "https://example.com/image.jpg"}],
    "resolution": "720P",
    "duration": 5,
})

# Keyframe-to-video (first + last frame)
task_id = create_vidu_task({
    "model": "vidu/viduq3-turbo_start-end2video",
    "prompt": "A cat jumps from windowsill to sofa",
    "media": [
        {"type": "image", "url": "https://example.com/first.png"},
        {"type": "image", "url": "https://example.com/last.png"},
    ],
    "resolution": "540P",
    "duration": 5,
})

# Reference-to-video
task_id = create_vidu_task({
    "model": "vidu/viduq2_reference2video",
    "prompt": "Man playing guitar in a cafe",
    "media": [
        {"type": "image", "url": "https://example.com/ref1.jpg"},
        {"type": "image", "url": "https://example.com/ref2.jpg"},
    ],
    "resolution": "720P",
    "size": "1280*720",
    "duration": 5,
})

エラー処理

エラー	考えられる原因	対処方法
401/403	DASHSCOPE_API_KEY が設定されていない、または無効	環境変数を確認し、北京リージョンのキーであることを確認してください
400 InvalidParameter	サポートされていない解像度とサイズの組み合わせ、不正な長さ、メディアの不足	サイズ表に照らしてパラメーターを検証してください
"does not support synchronous calls"	X-DashScope-Async: enable ヘッダーがない	必須のヘッダーを追加してください
429	レート制限またはクォータ	バックオフを設定して再試行してください
クロスリージョンエラー	モデルと API Key のリージョンが異なる	すべて北京リージョンであることを確認してください

出力先

• デフォルトの出力先：output/aliyun-vidu-video/videos/
• OUTPUT_DIR でベースディレクトリを上書きできます。

避けるべきパターン

• 上記の「重要なモデル名」に記載されていないモデル名は使用しないでください。
• この API を同期的に呼び出さないでください。非同期ヘッダーが必須です。
• 参照動画生成を使用する場合、size を省略しないでください。このモードでは必須です。
• Q2 モデルで audio=true を渡さないでください。音声生成をサポートしているのは Q3 モデルのみです。
• 動画の URL は24時間後に期限切れになります。すぐにダウンロードして保存してください。
• 画像から動画を生成する場合は、画像をちょうど1枚指定してください。キーフレームの場合は、画像をちょうど2枚（最初、次に最後）指定してください。
• viduq2_reference2video による参照動画生成では、画像のみ（1～7枚）が受け付けられます。viduq2-pro_reference2video では、画像（1～4枚）と任意の動画（1～2本）が受け付けられます。
• キーフレームモードでは、最初と最後のフレームのピクセル数の比率を0.8～1.25にしてください。

ワークフロー

1. ユーザーの意図を確認します：テキストから動画、画像から動画、キーフレーム、参照動画生成のいずれかです。
2. 機能と品質ティア（Q3 pro/turbo または Q2）に応じて、適切なモデル名を選択します。
3. 入力を準備します：プロンプト、および／または正しいタイプと有効な公開 URL を指定したメディア配列を用意します。
4. 解像度、サイズ、長さのパラメーターを設定します。
5. 非同期タスクを作成し、結果をポーリングします（15秒間隔を推奨）。
6. URL の期限切れ（24時間）前に、生成された動画をダウンロードして保存します。

参考資料

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