Kling 3.0 API移行ガイド：Motion Controlの使い分けと実装コード

Kling 2.6のリクエストは、モデル名を1つ書き換えるだけで安全に3.0へ移行できるわけではありません。Kling 3.0は正式提供されていますが、V3、Turbo、Omni、Motion Controlでは利用目的もスキーマも異なります。まず使うルートを決め、その後に音声、マルチショット、参照機能を1つずつ追加していくのが、最も堅実な移行方法です。

コードを書く前にエンドポイントを決める

Kling公式のVIDEO 3.0ガイドでは、VIDEO 3.0はVIDEO 2.6の後継、VIDEO 3.0 OmniはVIDEO O1の後継と位置付けられています。開発者APIではモデル別に操作が分かれているため、「Kling 3.0 API」は単一の共通リクエストボディではなく、複数のアクセス経路からなる製品群と考えるべきです。

統合時によくある失敗は、プロバイダー独自の簡略化されたスキーマとKlingの直接スキーマを混同することです。Kreaのホスト型リクエストは動作例としては有用ですが、そのURLやフィールドが公式Kling開発者ドキュメントにもそのまま当てはまる証拠にはなりません。

ルート全体の概要は、Kling API integration guideも参照してください。この記事ではKling 3.0への移行と、エンドポイントごとの挙動に絞って解説します。

Kling 2.6から3.0で変わること

Klingの公式モデルガイドが示す3.0の本質的な進化は、単なる高解像度化ではありません。制御性、連続性、映像と音声を組み合わせた演出が強化されています。以下は、Klingがこのモデルファミリーに帰属させている機能に基づく比較です。

実務上の違いは明確です。短いプロンプト1本を中心に組んでいた2.6の統合を、3.0では演出を指定した連続シーケンスへ発展させられます。Klingのガイドは、カメラ移動中にもキャラクター、物体、シーンの細部をより維持しやすいとしています。ただし、独立した一貫性ベンチマークは公開されていません。この主張と、実際に自社アプリケーションで検証できる内容は分けて扱うべきです。

最小構成で始めるKreaホスト型の非同期連携

動画生成は非同期処理です。アプリケーション側ではジョブを送信し、タスクIDを保持して、ポーリングまたはコールバックで完了を受け取り、完成した出力を保存します。モデルのレンダリング中に元のHTTPリクエストを開いたまま待たせてはいけません。

以下では、公開されているKling 3.0 API guideでリクエストとジョブのフィールドを確認できるため、KreaのKling 3.0エンドポイントを使います。プロバイダー固有のURLやフィールド名を置き換えるのは、利用する公式Klingスキーマを確認してからにしてください。

生成ジョブを送信する

import os
import time
import requests

API_KEY = os.environ["KREA_API_KEY"]
BASE_URL = "https://api.krea.ai"

payload = {
    "prompt": (
        "A paper boat crosses a rain-filled city gutter at night, "
        "macro camera, practical street lights, realistic water movement"
    ),
    "duration": 5,
    "mode": "std",
    "aspect_ratio": "16:9",
}

response = requests.post(
    f"{BASE_URL}/generate/video/kling/kling-3.0",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)
response.raise_for_status()
job = response.json()
job_id = job["job_id"]
print(f"submitted {job_id}")

Kreaのドキュメントにあるレスポンスには、job_idとscheduledなどの初期ステータスが含まれます。ステータス確認には別のジョブ照会エンドポイントを使う構成です。ポーリングを始める前に、ジョブIDと自システムの注文IDをデータベースへ保存してください。

タイムアウト付きでポーリングし、出力を保存する

TERMINAL = {"completed", "failed", "cancelled"}

for attempt in range(60):
    status_response = requests.get(
        f"{BASE_URL}/jobs/{job_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=30,
    )
    status_response.raise_for_status()
    job = status_response.json()
    status = job.get("status")

    if status in TERMINAL:
        break

    time.sleep(5)
else:
    raise TimeoutError(f"Kling job did not finish: {job_id}")

if job["status"] != "completed":
    raise RuntimeError(f"Kling job ended as {job['status']}: {job_id}")

video_url = job["result"]["urls"][0]
print(video_url)

Kreaの例では51秒と2分3秒の処理時間が示されています。Klingの生成時間を固定値として約束するのではなく、キューの待ち時間を見込んだタイムアウトを設定しましょう。

本番環境では、Webhookを使えば繰り返しポーリングを省けます。ジョブIDが自システムで作成したジョブに対応することを検証し、ハンドラーは冪等に実装してください。署名のないコールバックだけを本人性の証明として扱ってはいけません。

3.0の制御項目は1つずつ追加する

パラメータ名は、Klingの直接APIとホスト型プロバイダーの間で異なります。プロバイダー固有のJSONをアプリケーション全体へ広げず、小さな互換レイヤーを用意するのがおすすめです。

公式ガイドでは、ネイティブ音声、要素参照、マルチショットの物語表現、5つの会話対応言語が案内されています。ただし、選んだAPIエンドポイントでは、これらモデルファミリー全体の機能の一部しか公開されていない場合があります。

カスタムのマルチショットペイロード

Kreaのドキュメントでは、時間を指定したmulti_promptのビートを使うスキーマが採用されています。ホスト型統合では参考になるパターンです。

{
  "multi_prompt": [
    {
      "prompt": "Wide shot: a lighthouse stands on a calm rocky coast at dusk.",
      "duration": 4
    },
    {
      "prompt": "Storm clouds arrive; waves rise and spray crosses the rocks.",
      "duration": 4
    },
    {
      "prompt": "Night rain begins as the lighthouse beam sweeps toward camera.",
      "duration": 4
    }
  ],
  "duration": 12,
  "generate_audio": true,
  "mode": "std",
  "aspect_ratio": "16:9"
}

トップレベルの尺が各ビートの尺の合計と一致することを検証してください。Kreaは3ビート・12秒のテストで12.04秒の結果を報告しているため、ファイルの長さがミリ秒単位まで数学的にぴったり一致するとは考えないほうがよいでしょう。

Kreaでは各ビートが512文字まで、演出付きシーケンス全体は15秒までに制限されています。長いシーン説明を書くのではなく、被写体、変化、カメラを含むショット指示として各ビートを記述してください。直接Klingのルートで公式ショット記法を使う場合も、タイムラインの考え方は維持し、アダプター境界でペイロードを変換します。

音声と言語に関する制約

公式ガイドでは、会話対応言語として中国語、英語、日本語、韓国語、スペイン語を挙げ、方言、アクセント、キャラクター別の会話、複数言語が混在するシーンにも触れています。未対応の会話入力は英語へ翻訳されるとされているため、多言語アプリケーションではすべての入力言語がそのまま維持されるとは想定できません。

音声はコスト面でも判断が必要です。Kreaが公表している料金では、stdは音声なしで1秒あたり$0.1764、音声ありで$0.2646、proは音声なしで$0.2352、音声ありで$0.3528です。4Kの掲載料金は、音声の有無にかかわらず1秒あたり$0.441です。これはKreaの料金であり、Kling API共通の料金表ではありません。

反復制作では、まず無音でドラフトを生成し、最終候補のstdまたはproにだけ音声を有効化する流れが合理的です。

本番運用で押さえるコスト・速度・失敗対策

Klingの公式コンシューマー向けガイドでは、VIDEO 3.0の料金を、ネイティブ音声なしの720pで1秒あたり6クレジット、1080pで8クレジット、音声ありの720pで9クレジット、1080pで12クレジットとしています。Voice Controlには1秒あたり2クレジットが追加されます。これらの数値は同ガイド内での相対的なコストを示すものであり、稼働中の開発者向け料金ページを確認せずに、開発者APIのドル建て価格へ換算すべきではありません。

選択基準は、単に「どのモデルが最も安いか」ではありません。課金と運用を含めて判断する必要があります。

失敗は種類ごとに処理します。

1. 一時的なプロバイダーエラーは、上限付きの指数バックオフで再試行する。
2. 無効なパラメータは、アダプターでペイロードを修正するまで再試行しない。
3. ネットワークタイムアウトで気付かない重複ジョブが作られないよう、クライアント側で冪等性キーまたは注文IDを保持する。
4. バッチ生成には、ドルまたはクレジットの上限を必ず設定する。
5. プロバイダーの一時URLが期限切れになる前に、結果をダウンロードまたは永続ストレージへコピーする。
6. モデルのバリアント、尺、音声設定、解像度ティア、プロバイダーをまとめて記録する。コスト集計において「Kling 3.0」だけでは不十分。

Kling 2.6から3.0への移行チェックリスト

1. 既存の2.6呼び出しを棚卸しする。 モデルID、画像入力、開始・終了フレーム、尺、音声、コールバックの挙動を記録する。
2. 3.0ファミリー内のルートを選ぶ。 プロンプト主体のシネマティック生成にはV3、高速ルートにはTurbo、O1系のマルチモーダル経路にはOmni、モーション参照を使う場合はMotion Controlを選ぶ。
3. プロバイダーアダプターを作る。 直接Kling、Krea、その他のホスト型スキーマは、それぞれ別の変換層の背後に置く。
4. 最小リクエストから移行する。 音声やマルチショット制御を追加する前に、5秒・無音・16:9の生成をテストする。
5. テストごとに制御項目を1つだけ足す。 尺、音声、ショット指示、参照の順に検証する。問題のあるフィールドを特定しやすくなる。
6. 終端ステータスをテストする。 成功、失敗、キャンセル、タイムアウト、重複コールバック、出力URLの期限切れをカバーする。
7. コストを計測したシャドーローンチを行う。 固定のプロンプトセットを同じ尺・出力ティアで2.6と3.0にかけ、品質または制御性の向上が新ルートを正当化するか判断する。

モデルIDをロールバックしても、ビジネスロジック、課金制御、結果処理を変えずに済む状態になれば、移行は完了です。

Kling 3.0 API FAQ

公式のKling 3.0 APIはありますか？

あります。Klingの公式開発者ドキュメントでは3.0のモデル別APIページが公開されており、Klingの公式ガイドでもVIDEO 3.0はVIDEO 2.6の後継として案内されています。一部のページはクライアントレンダリングされるため、正確なエンドポイントスキーマは稼働中の開発者コンソールで確認してください。

Motion ControlはKling 3.0のパラメータですか？

そうとは限りません。Motion ControlはKlingエコシステム内で独自のモデルページを持つ専門機能です。通常のテキスト動画生成リクエストへ未検証のmotion_controlフィールドを追加するのではなく、選択したプロバイダーが文書化している操作と入力スキーマを使用してください。

Kling VIDEO 3.0は最長何秒の動画を生成できますか？

Klingの公式モデルガイドでは、VIDEO 3.0は3～15秒の柔軟な出力に対応するとされています。ただし、特定のホスト型ルートやTurboルートには、より狭い制限が設けられていることがあります。選択したエンドポイントで確認してください。

Kling 3.0はネイティブ音声に対応していますか？

公式VIDEO 3.0ガイドでは対応するとされ、キャラクター別の会話、複数言語、方言、アクセントが説明されています。音声が任意かどうか、また料金体系はどうなっているかは、エンドポイントまたはプロバイダーのスキーマに依存します。

Kling 3.0 Omniは通常のKling 3.0と同じですか？

いいえ。同じではありません。KlingはVIDEO 3.0を2.6の後継、VIDEO 3.0 OmniをO1の後継として位置付けています。プロバイダーのページでは別のモデルIDとして提供され、参照や音声の制御も異なる場合があります。

KlingのWebサブスクリプションでAPI呼び出しを支払えますか？

稼働中のアカウントドキュメントに明記されるまでは、コンシューマー向けサブスクリプションと開発者APIの課金は別物として扱ってください。通常、APIルートには独自の開発者アカウント、キー、課金設定が必要です。

移行の境界線はシンプルです。2.6統合のジョブライフサイクルは維持し、モデル固有のアダプターだけを置き換え、追加する3.0の制御項目は実際に提供しているルートごとに検証します。これにより、送信自体は成功したものの、誤ったバリアント、音声モード、課金ティアを静かに使ってしまうという、最も高くつく失敗を避けられます。