aliyun-kling-video

Kling V3 動画生成

検証

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

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

出力と証拠

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

前提条件

• 依存関係をインストールします（venv の使用を推奨）：

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

• 環境に DASHSCOPE_API_KEY を設定します（北京リージョンの API Key が必要です）。
• 百炼控制台 で Kling を有効にします。「kling」を検索して有効化してください。

重要なモデル名

• kling/kling-v3-video-generation — 標準モデル：t2v、i2v（最初のフレーム、最初と最後のフレーム）
• kling/kling-v3-omni-video-generation — omni モデル：参照動画からの生成、動画編集、複数の被写体の参照に対応

機能

機能	モデル	必要なメディア
テキストから動画を生成	両方	なし
スマートストーリーボード（複数ショット）	両方	なし（multi_prompt を使用）
画像から動画を生成（最初のフレーム）	両方	first_frame
画像から動画を生成（最初と最後のフレーム）	両方	first_frame + last_frame
参照動画から生成	omni のみ	refer および／または feature
動画編集	omni のみ	base + 任意の refer

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

リージョン：北京のみ。シンガポールのエンドポイントはありません。

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

リクエスト（入力）

• prompt（文字列、条件付き）— 最大 2500 文字。shot_type=intelligence の場合は必須です。omni の参照動画からの生成では、メディアを参照するために <<<element_1>>>、<<<image_1>>>、<<<video_1>>> を使用します。
• negative_prompt（文字列、任意）— 除外する内容
• media（配列、任意）— type と url を持つメディアオブジェクト：
  • 標準モデルの種類：first_frame、last_frame
  • omni モデルの種類：first_frame、last_frame、refer、base、feature
• multi_shot（ブール値、任意）— 複数ショットの生成を有効にします（デフォルト：false）
• shot_type（文字列、条件付き）— intelligence（AI による自動分割）または customize（手動）。multi_shot=true の場合は必須です。
• multi_prompt（配列、任意）— shot_type=customize の場合のショットごとのプロンプト
• element_list（配列、任意）— 複数の被写体の要素画像（omni モデルのみ）
• keep_original_sound（文字列、任意）— 動画で使用する no（デフォルト）または yes（omni モデルのみ）

リクエスト（パラメーター）

• mode（文字列、任意）— pro（デフォルト、1080P）または std（720P）
• aspect_ratio（文字列、条件付き）— 16:9（デフォルト）、9:16、1:1。t2v と参照動画からの生成では必須です。
• duration（整数、任意）— 動画の長さ [3, 15] 秒（デフォルト：5）。参照動画を使用する場合は [3, 10] です。
• audio（ブール値、任意）— 音声を生成します（デフォルト：false）。料金に影響します。
• watermark（ブール値、任意）— 「可灵 AI」ウォーターマークを追加します（デフォルト：false）

メディア入力の制限

画像（first_frame、last_frame、refer）：

• 形式：JPEG、JPG、PNG（透明度なし）
• 解像度：各辺 [300, 8000] ピクセル
• 最大サイズ：10MB

動画（base、feature）：

• 形式：mp4、mov
• 長さ：3～10 秒
• 解像度：各辺 [720, 2160] ピクセル
• フレームレート：24～60 fps
• 最大サイズ：200MB

メディアの組み合わせルール

kling/kling-v3-video-generation：

• i2v の最初のフレーム：first_frame（画像 1 枚）
• i2v の最初と最後のフレーム：first_frame + last_frame（各 1 枚）

kling/kling-v3-omni-video-generation（上記すべてに加えて）：

• 参照：feature のみ（動画 1 本）、または refer のみ（要素を含めて最大 7 個）、または feature+refer（動画 1 本 + 要素を含めて最大 4 個）、または feature+first_frame（動画 1 本 + 画像 1 枚）
• 動画編集：base のみ（動画 1 本）、または base+refer（動画 1 本 + 要素を含めて最大 4 個）

応答（タスク作成）

• output.task_id（文字列）— 24 時間有効
• output.task_status（文字列）— PENDING | RUNNING | SUCCEEDED | FAILED | CANCELED
• request_id（文字列）

応答（タスク結果）

• output.video_url（string）— 生成された動画の URL
• output.watermark_video_url（string）— 透かし入り動画の URL
• usage.duration（integer）、usage.size（string）、usage.fps（integer）、usage.audio（boolean）

クイックスタート（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_kling_task(req: dict) -> str:
    """Create a Kling video generation task and return task_id."""
    payload = {
        "model": req.get("model", "kling/kling-v3-video-generation"),
        "input": {"prompt": req.get("prompt", "")},
        "parameters": {
            "mode": req.get("mode", "pro"),
            "duration": req.get("duration", 5),
            "audio": req.get("audio", False),
            "watermark": req.get("watermark", False),
        },
    }
    if req.get("aspect_ratio"):
        payload["parameters"]["aspect_ratio"] = req["aspect_ratio"]
    if req.get("negative_prompt"):
        payload["input"]["negative_prompt"] = req["negative_prompt"]
    if req.get("media"):
        payload["input"]["media"] = req["media"]

    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_kling_task({
    "prompt": "一只小猫在月光下奔跑",
    "aspect_ratio": "16:9",
    "duration": 5,
    "mode": "std",
})

# Image-to-video (first frame)
task_id = create_kling_task({
    "prompt": "花朵绽放的延时摄影",
    "media": [{"type": "first_frame", "url": "https://example.com/flower.jpg"}],
    "duration": 5,
})

# Reference-to-video with omni model
task_id = create_kling_task({
    "model": "kling/kling-v3-omni-video-generation",
    "prompt": "一只<<<element_1>>>在月光下奔跑",
    "media": [{"type": "refer", "url": "https://example.com/cat.jpg"}],
    "aspect_ratio": "16:9",
})

エラー処理

エラー	考えられる原因	対処方法
401/403	API Key がない、または無効です	環境変数を確認してください。北京リージョンである必要があります
400 InvalidParameter	メディアの組み合わせが不適切、または必須パラメーターがありません	モデルのメディア要件に照らして検証してください
"does not support synchronous calls"	X-DashScope-Async: enable ヘッダーがありません	必須のヘッダーを追加してください
429	レート制限またはクォータ	バックオフして再試行してください

出力先

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

アンチパターン

• kling/kling-v3-video-generation または kling/kling-v3-omni-video-generation 以外のモデル名は使用しないでください。
• この API を同期的に呼び出さないでください。非同期ヘッダーが必須です。
• 標準モデルでは refer、base、feature のメディアタイプを使用しないでください。これらは omni モデルのみで使用してください。
• 互換性のないメディアの組み合わせは使用しないでください。
• 動画 URL には有効期限があります。すぐにダウンロードして保存してください。
• 北京リージョンのみ対応です。シンガポールのエンドポイントは使用しないでください。

ワークフロー

1. ユーザーの意図（t2v、i2v、参照画像からの動画生成、編集、またはストーリーボード）を確認します。
2. 適切なモデルを選択します（基本的な t2v/i2v には標準モデル、参照画像を使った生成や編集には omni モデル）。
3. 適切なタイプと有効な URL を指定してメディア配列を準備します。
4. 非同期タスクを作成し、結果をポーリングします。
5. URL の有効期限が切れる前に生成された動画をダウンロードして保存します。

参考資料

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