kling-video-generator

Kling 3.0 Omni 動画ジェネレーター

このスキルを使用すると、Kling 3.0 Omni モデルで動画を生成・編集できます。ユーザーの意図に基づいて API リクエストを組み立てるための体系的なワークフローを提供し、モデルの複雑なパラメーター制約への準拠を確保します。

リファレンスファイル

このスキルには、以下のリファレンスファイルが含まれています。

• references/api_reference.md — 公式 API パラメーターの完全なリファレンス。すべてのフィールド、型、制約、相互排他ルール（R1～R10）、機能マトリックス、呼び出し例を含みます。API 呼び出しを組み立てる前に、このファイルを読んでください。
• references/prompt_guide.md — Kling 3.0 Omni のプロンプト作成原則、公式フォーマット、テンプレート構文、主なシナリオすべての少数ショット例。
• scripts/kling_api.py — JWT 認証、タスク作成、ポーリングを行う Python ユーティリティクラス。

---

主な機能

• テキストから動画を生成：テキストによる説明から動画を生成します。
• 画像から動画を生成：説明プロンプトを使って静止画像に動きを付けます。
• 動画から動画へ（編集）：プロンプトに基づいて既存の動画を編集します（例：被写体やスタイルの変更）。
• 動画から動画へ（参照）：既存の動画をカメラワークやスタイルの参照として使用します。
• マルチショット生成：複数の異なるシーンやショットで構成される動画を作成します。
• 音声生成：会話や効果音を含む、音声と同期した動画を生成します。

---

ワークフロー：ユーザーの意図から API 呼び出しまで

Kling API を正しく使用するには、API ペイロードを組み立てるための以下の意思決定ワークフローに必ず従ってください。このプロセスは、プロンプト設計とパラメーター構築の 2 つの段階に分かれています。

ステージ 1：プロンプト設計

API 呼び出しを組み立てる前に、まずユーザーのリクエストに基づいてプロンプトを設計する必要があります。プロンプトの品質は、良い結果を得るうえで最も重要な要素です。

1. プロンプトガイドを参照する：効果的なプロンプト作成の基本原則、公式フォーマット、少数ショット例を理解するために、/home/ubuntu/skills/kling-video-generator/references/prompt_guide.md を読みます。

2. シナリオを特定する：ユーザーが以下のどのシナリオを求めているかを判断します。

   • 単一ショット動画（テキスト、画像、または動画から生成）
   • マルチショット動画（複数のシーンで構成されるストーリーボード）

3. プロンプトを作成する：

   • 単一ショットの場合は、ガイドのフォーマットに従って、詳細なプロンプトを 1 つ作成します。
   • マルチショットの場合は、各ショット／シーンに個別のプロンプトを作成します。
   • テンプレート構文を使用する：ユーザーが参照画像、要素、または動画を提供した場合は、プロンプト内でそれらを明示的に参照するために、<<<image_1>>>、<<<element_1>>>、<<<video_1>>> のテンプレート構文を必ず使用してください。これは Omni モデルの中核機能です。

ステージ 2：パラメーター構築

プロンプトの準備ができたら、この決定木に従って最終的な API リクエストペイロードを組み立てます。これにより、広範なテストを通じて判明したすべてのパラメーター制約と相互依存関係が確実に守られます。

graph TD
    A[Start] --> B{Multi-shot or Single-shot?};
    B -- Multi-shot --> C[Set `multi_shot: true`];
    B -- Single-shot --> D[Set `multi_shot: false`];

    C --> E{Set `shot_type: "customize"`};
    E --> F[Construct `multi_prompt` array from prompts];
    F --> G[Calculate total duration from `multi_prompt`];
    G --> H[Set top-level `duration`];
    H --> Z[Final Payload];

    D --> I{Video input provided?};
    I -- Yes --> J{Editing or Reference?};
    I -- No --> K[Text/Image-to-Video Path];

    J -- Editing --> L[Set `refer_type: "base"`];
    J -- Reference --> M[Set `refer_type: "feature"`];

    L --> N[Ignore `duration` parameter];
    M --> O[Set `aspect_ratio`];
    N --> P{Audio handling};
    O --> P;

    K --> Q{Audio handling};
    P --> R{Audio handling};

    subgraph R [Audio Handling]
        direction LR
        R1{Want audio output?} -- Yes --> R2[Set `sound: "on"`];
        R1 -- No --> R3[Set `sound: "off"`];
        R2 --> R4{Video input exists?};
        R4 -- Yes --> R5[ERROR: `sound:on` is incompatible with video input];
        R4 -- No --> R6[OK];
    end

    Q --> Z;
    R6 --> Z;
    R3 --> Z;
    R5 --> Stop([Stop/Error]);

主要なパラメーターのルール（テスト結果に基づく）

以下はすべてを網羅したリストではなく、特に重要で見落としやすいルールをまとめたものです。必ず守ってください。詳しくは、prompt_guide.mdを参照してください。

パラメーター	ルール
refer_type	明示的に指定する必要があります。省略しないでください。デフォルトはbaseですが、これは信頼できません。編集にはbase、参照にはfeatureを使用してください。
duration	baseモードでは無視されます。customizeモードでは、multi_promptの各durationの合計と一致する必要があります。
sound	video_listと併用できません。参照動画を指定する場合、onにすることはできません。
shot_type	Omniモデルでmulti_shot: trueを指定する場合、customizeである必要があります。intelligenceはサポートされていません。
multi_prompt	indexは1から始める必要があります。合計durationはトップレベルのdurationと一致する必要があります。最大6ショットです。
aspect_ratio	featureモードでは必須です。
image_list	動画入力がない場合は最大7枚、動画入力がある場合は最大4枚です。

---

実行

動画生成タスクを実行するには、認証とポーリングを処理する付属のPythonスクリプトを使用します。

1. 環境変数を設定する：KLING_ACCESS_KEYとKLING_SECRET_KEYが設定されていることを確認します。

2. ペイロードを構築する：上記のワークフローに従って、API呼び出し用のJSONペイロードを作成します。

3. スクリプトを実行する：

   from kling_api import KlingAPI
   
   # 環境変数からキーを取得
   access_key = os.environ.get("KLING_ACCESS_KEY")
   secret_key = os.environ.get("KLING_SECRET_KEY")
   api = KlingAPI(access_key, secret_key)
   
   # 構築したペイロード
   payload = {
       "model_name": "kling-v3-omni",
       # ... ワークフローに基づくその他のパラメーター ...
   }
   
   # タスクを作成してポーリング
   task_response = api.create_omni_video_task(payload)
   if task_response and task_response.get("code") == 0:
       task_id = task_response.get("data", {}).get("task_id")
       print(f"タスクを作成しました: {task_id}")
       result = api.poll_for_completion(task_id)
       if result:
           print("最終動画のURL:", result.get("videos", [{}])[0].get("url"))
   

この構造化された手順により、Kling 3.0 Omni APIの細かな仕様と制約を正しく処理でき、エラーが減り、より予測しやすい結果が得られます。