Kling Videos Generation API 連携説明

Kling video generation API guide - Ace Data Cloud

本文では、カスタムパラメータを入力することでKling公式の動画を生成できる Kling Videos Generation API の連携説明を紹介します。

​

申請フロー

Kling Videos Generation API を使用するには、まず Ace Data Cloud コンソール で API Token を取得し、予備として保管してください。

まだログインまたは登録していない場合は、ログインページへ自動的に移動して登録とログインを促され、完了後に現在のページへ自動的に戻ります。

1つの API Token でプラットフォーム上のすべてのサービスを呼び出すことができ、サービスごとに個別申請する必要はありません。 初回申請時には無料クレジットが付与され、無料で体験できます。クレジットが不足した場合は コンソール で共通残高をチャージできます。

📘 完全なドキュメント：Kling Videos Generation API →

​

基本的な使用方法

まず基本的な使用方法を理解しましょう。プロンプト prompt、生成アクション action、開始フレーム参照画像 start_image_url およびモデル model を入力すると、処理後の結果を取得できます。まず action フィールドを簡単に渡す必要があり、その値は text2video です。主に3つのアクションが含まれます：テキストから動画（text2video）、画像から動画（image2video）、動画の拡張（extend）。次にモデル model を入力する必要があります。現在は主に kling-v1、kling-v1-6、kling-v2-master、kling-v2-1-master、kling-v2-5-turbo、kling-v2-6、kling-v3、kling-v3-omni、kling-o1 モデルがあり、具体的な内容は以下のとおりです：

ここで Request Headers を設定していることがわかります。内容は以下のとおりです：

• accept：どの形式のレスポンス結果を受け取りたいか。ここでは application/json、つまり JSON 形式を入力します。
• authorization：API を呼び出すためのキー。申請後は直接プルダウンで選択できます。

また、Request Body を設定しています。内容は以下のとおりです：

• model：動画を生成するモデル。主に kling-v1、kling-v1-6、kling-v2-master、kling-v2-1-master、kling-v2-5-turbo、kling-v2-6、kling-v3、kling-v3-omni、kling-o1 モデルがあります。
• mode：動画を生成するモード。選択可能な値は標準モード std、高速モード pro、ネイティブ 4K モード 4k です。そのうち 4k は kling-v3 と kling-v3-omni のみ対応し、camera_control（カメラワーク制御）とは互換性がありません。
• action：今回の動画生成タスクのアクション。主に3つのアクションが含まれ、それぞれ：テキストから動画（text2video）、画像から動画（image2video）、動画の拡張（extend）です。
• start_image_url：画像から動画のアクション image2video を選択した場合に必須となる、アップロード済み開始フレーム参照画像のリンクです。
• end_image_url：画像から動画の場合は任意で、終了フレームを指定します。
• duration：動画の長さ、単位は秒です。kling-v3 と kling-v3-omni は3～15秒の整数の長さをサポートします。kling-o1 は5秒のみサポートします。その他のモデルは5秒または10秒をサポートします。
• generate_audio：音声を同時に生成するかどうか。任意、ブール値です。kling-v3、kling-v3-omni および kling-v2-6（pro モードのみ）に対応しています。デフォルトは false です。
• aspect_ratio：動画のアスペクト比。任意で、16:9、9:16、1:1 をサポートし、デフォルトは 16:9 です。
• cfg_scale：関連性の強度、範囲は [0,1] で、大きいほどプロンプトに適合します。
• camera_control：任意。カメラの動きを制御するオブジェクトパラメータで、type/simple プリセットおよび horizontal、vertical、pan、tilt、roll、zoom などの設定をサポートします。
• negative_prompt：任意。表示させたくないネガティブプロンプトで、最大200文字です。
• image_list：Omni 参照画像リスト。kling-o1 および kling-v3-omni モデルに適用され、使用方法は下記の「Omni 万能参照」を参照してください。
• video_list：Omni 参照動画リスト（動画編集に対応）。kling-o1 および kling-v3-omni モデルに適用され、使用方法は下記の「Omni 万能参照」を参照してください。
• prompt：プロンプト。
• callback_url：結果のコールバックが必要なURL。
• async：任意。true に設定すると、インターフェースは直ちに task_id を返します。callback_url を提供する必要はなく、その後、対応するタスク照会インターフェースを通じてポーリングして結果を取得します。

選択後、右側にも対応するコードが生成されていることがわかります。図のとおりです：

「Try」ボタンをクリックするとテストできます。上図のとおり、ここでは以下の結果を取得しました：

{
  "success": true,
  "video_id": "900798310464749610",
  "video_url": "https://cdn.acedata.cloud/assets/examples/kling/6c68c267-065b-4423-b66b-a0e4c59ee0d5-6a664a591a53.mp4",
  "duration": "5.041",
  "state": "succeed",
  "task_id": "6c68c267-065b-4423-b66b-a0e4c59ee0d5"
}

返却結果には複数のフィールドがあり、以下のとおり紹介します：

• success、この時点の動画生成タスクのステータス状況です。
• task_id、この時点の動画生成タスクIDです。
• video_id、この時点の動画生成タスクの動画IDです。
• video_url、この時点の動画生成タスクの動画リンクです。
• duration、この時点の動画生成タスクの動画リンクの長さです。
• state、この時点の動画生成タスクのステータスです。

満足できる動画情報を取得できたことがわかります。結果内の data の動画リンクアドレスに基づいて、生成されたKling動画を取得するだけです。

また、対応する連携コードを生成したい場合は、直接コピーして生成できます。たとえば CURL のコードは以下のとおりです：

curl -X POST 'https://api.acedata.cloud/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-v3",
  "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle."
}'

​

モデル機能マトリクス

モデルごとにパラメータへの対応状況は大きく異なります。以下のマトリクスは Kling 公式 video models ドキュメント をもとに整理したものです。呼び出す前に、現在の model / mode / duration の組み合わせが必要な機能に対応しているかを確認してください。そうしないと、model/mode/duration(...) is not supported with image_tail などのエラーが返されます。

モデル	モード	end_image_url（開始・終了フレーム）	generate_audio（音声）	camera_control（カメラワーク）	備考
kling-v1	std / pro	✅ duration=5 のみ	❌	✅ duration=5 のみ	extend は negative_prompt と cfg_scale をサポートしない
kling-v1-6	std	❌	❌	❌	複数画像から動画生成、extend は全モードで利用可能
kling-v1-6	pro	✅	❌	❌
kling-v2-master	—	❌	❌	❌	単一モード、duration=5/10 のみ
kling-v2-1-master	—	❌	❌	❌	単一モード、duration=5/10 のみ
kling-v2-5-turbo	std	❌	❌	❌
kling-v2-5-turbo	pro	✅	❌	❌
kling-v2-6	std	❌	❌	❌
kling-v2-6	pro	✅	✅	❌	音声を同時にサポートする唯一の非 v3 モデル
kling-v3	std / pro	✅	✅	✅	duration の範囲は 3～15 秒
kling-v3	4k	✅	✅	❌	4K モードはカメラワークと互換性がない
kling-v3-omni	std / pro / 4k	✅	✅	❌
kling-o1	std / pro	✅	❌	❌	duration=5 のみサポート

注意事項：

• mode=4k は kling-v3 と kling-v3-omni のみがサポートしています。また、camera_control（カメラワーク）とは排他的です。
• end_image_url は action=image2video の場合にのみ start_image_url と組み合わせて使用できます。end_image_url のみ（start_image_url なし）を渡すと拒否されます。
• kling-v3 / kling-v3-omni は任意の 3～15 秒の整数 duration を受け付けます。kling-o1 は 5 のみを受け付け、その他のモデルは 5 または 10 のみを受け付けます。
• generate_audio のデフォルトは false です。kling-v3、kling-v3-omni、および kling-v2-6（pro モード）のみがサポートしています。

​

動画拡張機能

すでに生成された Kling 動画を続けて生成したい場合は、パラメータ action を extend に設定し、続けて生成する動画の ID を入力できます。動画 ID の取得は基本的な使用方法に従って行います。以下の図のとおりです：

このとき、動画の ID は以下であることが確認できます：

"video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c"

注意：ここでの動画内の video_id は生成後の動画の ID です。動画の生成方法がわからない場合は、上記の基本的な使用方法を参照して動画を生成できます。

次に、カスタム動画生成のために、次のステップで拡張する必要があるプロンプトを必ず入力する必要があります。以下の内容を指定できます：

• model：動画を生成するモデル。主に kling-v1、kling-v1-5、kling-v1-6 モデルがあります。
• mode：動画を生成するモード。オプション値は標準モード std、高速モード pro、およびネイティブ 4K モード 4k（kling-v3 と kling-v3-omni のみがサポートし、カメラワーク制御とは互換性がありません）です。
• duration：今回の動画生成タスクの動画時間。主に 5 秒と 10 秒が含まれます。
• start_image_url：画像から動画への動作 image2video を選択した場合、アップロードが必要な開始フレームの参考画像リンクです。
• prompt：プロンプト。

入力例は以下のとおりです：

入力が完了すると、次のコードが自動生成されます：

対応する Python コード：

import requests

url = "https://api.acedata.cloud/kling/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "extend",
    "model": "kling-v1",
    "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c",
    "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle.",
    "duration": 10
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

実行をクリックすると、以下のような結果が得られることが確認できます：

{
  "success": true,
  "video_id": "bbc3b105-ac72-4de2-8390-0cb37dc7d41e",
  "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
  "duration": "9.6",
  "state": "succeed",
  "task_id": "3ece87e6-3ee3-4f5e-bd70-5ae5eca89a23"
}

結果の内容は上記と一致していることがわかり、これにより動画の拡張機能が実現されます。

​

Omni 万能リファレンス（動画編集 / 参考動画 / 複数画像リファレンス）

kling-o1 と kling-v3-omni は 2 つの独立したモデルであり、どちらも「万能リファレンス」機能をサポートしています。テキストから動画生成（action=text2video）をベースに、参考画像または参考動画を追加で渡すことで、複数画像リファレンス、参考動画、および既存動画の直接編集を実現できます。

コア規約：参考素材は、prompt 内で &lt;&lt;<image_1>>>、&lt;&lt;<video_1>>> の形式（番号は 1 から開始）により、image_list / video_list 内の対応する位置の素材を参照する必要があります。そうして初めてモデルはこれらの参考を適用します。素材のみを渡してプロンプト内で参照しない場合、素材は無視されます。

セキュリティに関する説明：現在の API では element_list を公開していません。Kling Element Library の ID はテナント分離されていないため、テナント分離を提供する Element Management API が提供されるまで、image_list を使用して被写体の参考画像を渡してください。

Omni リクエストは negative_prompt、cfg_scale、または camera_control をサポートせず、mode=4k も使用できません。参考動画を含む場合、generate_audio は必ず false にする必要があります。

​

参考動画と動画編集（video_list）

video_list は参照動画を渡すために使用され、本機能で最もよく使われるシナリオです。配列要素のフィールドは以下のとおりです：

• video_url：参照動画リンク。空にすることはできません。MP4/MOV 動画は最大 1 本、ファイルサイズは ≤200MB、フレームレートは 24～60fps。kling-o1 では長さ 3～10 秒、幅と高さはそれぞれ 700～2160px が必要です。kling-v3-omni では長さ 3～15.5 秒、幅と高さはそれぞれ 700～4553px、総ピクセル数は ≤8,294,400、アスペクト比は 0.4～2 が必要です。
• refer_type：参照タイプ。base（デフォルト、編集対象のベース動画、すなわち「動画を直接編集する」であり、要素の追加・削除・変更、構図変更、スタイル変更、色変更、天気変更などが可能）または feature（特徴参照、そのスタイル / カメラワーク / 次のショットへの継続撮影を参照）を選択できます。
• keep_original_sound：元動画の音声を保持するかどうか。yes（保持）または no（削除）を選択できます。

注意：参照動画がある場合、generate_audio は false にする必要があります。refer_type=base の動画には、開始フレーム / 終了フレームを追加指定できません。

既存の動画を編集する（動画をアニメ風に変更する）CURL の例は以下のとおりです：

curl -X POST 'https://api.acedata.cloud/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-o1",
  "mode": "std",
  "duration": 5,
  "prompt": "把 <<<video_1>>> 改成电影级动漫风格，保留原有的运动和构图",
  "video_list": [
    {
      "video_url": "https://cdn.acedata.cloud/your-reference-video.mp4",
      "refer_type": "base",
      "keep_original_sound": "no"
    }
  ]
}'

​

複数画像参照（image_list）

image_list は参照画像（要素 / シーン / スタイルなど）を渡すために使用されます。配列要素のフィールドは以下のとおりです：

• image_url：参照画像リンク。空にすることはできません。要件：形式は .jpg/.jpeg/.png、ファイルサイズは ≤10MB、最短辺は ≥300px、アスペクト比は 1:2.5 ～ 2.5:1。
• type：任意。指定しない場合は純粋な参照画像として扱われます。first_frame / end_frame を指定した場合は、それぞれ開始フレーム / 終了フレームとして扱われます（start_image_url / end_image_url と同等）。

使用時は、prompt 内で &lt;&lt;<image_1>>>、&lt;&lt;<image_2>>> により参照する必要があります。数の制限：参照動画がない場合、参照画像は ≤ 7；参照動画がある場合、参照画像は ≤ 4。開始 / 終了フレームのみを渡す場合も、start_image_url / end_image_url を直接使用できますが、終了フレームは開始フレームと一緒に使用する必要があります。

注意：start_image_url / end_image_url と image_list を同時に渡す場合、開始 / 終了フレームは image_list より前に配置されるため、&lt;&lt;<image_N>>> の番号対応関係に影響する可能性があります。どちらか一方を選択することを推奨します：開始 / 終了フレームが必要な場合は、image_list 内で直接 type を指定し、start_image_url / end_image_url と混在させないでください。

複数画像参照で動画を生成する CURL の例：

curl -X POST 'https://api.acedata.cloud/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-o1",
  "mode": "std",
  "duration": 5,
  "prompt": "让 <<<image_1>>> 里的人物站在 <<<image_2>>> 的场景中，电影感光线",
  "image_list": [
    { "image_url": "https://cdn.acedata.cloud/subject.png" },
    { "image_url": "https://cdn.acedata.cloud/scene.png" }
  ]
}'

​

非同期コールバック

Kling Videos Generation API の生成には比較的長い時間がかかり、約 1～2 分を要します。API が長時間応答しない場合、HTTP リクエストは接続を維持し続け、追加のシステムリソース消費につながるため、本 API では非同期コールバックもサポートしています。

全体のフローは次のとおりです：クライアントがリクエストを開始する際に、追加で callback_url フィールドを指定します。クライアントが API リクエストを開始した後、API は直ちに結果を返し、現在のタスク ID を表す task_id フィールド情報を含みます。タスクが完了すると、生成された動画の結果は POST JSON の形式でクライアントが指定した callback_url に送信され、その中にも task_id フィールドが含まれるため、タスク結果を ID によって関連付けることができます。

以下の例で、具体的な操作方法を見ていきます。

まず、Webhook コールバックは HTTP リクエストを受信できるサービスです。開発者は自分で構築した HTTP サーバーの URL に置き換える必要があります。ここではデモを容易にするため、公開 Webhook サンプルサイト https://webhook.site/ を使用します。このサイトを開くと、図のように Webhook URL を取得できます：

この URL をコピーすると、Webhook として使用できます。ここでの例は https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3 です。

次に、フィールド callback_url を上記の Webhook URL に設定し、対応するパラメータを入力します。具体的な内容は図のとおりです：

実行をクリックすると、すぐに以下のような結果が得られます：

{
  "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}

しばらく待つと、https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3 上で生成された動画の結果を観察できます。図のとおりです：

内容は以下のとおりです：

{
    "success": true,
    "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c",
    "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
    "duration": "5.1",
    "state": "succeed",
    "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}

結果には task_id フィールドがあり、その他のフィールドは上記と同様であることが分かります。このフィールドにより、タスクの関連付けを実現できます。

​

エラー処理

API の呼び出し時にエラーが発生した場合、API は対応するエラーコードと情報を返します。例えば：

• 400 token_mismatched：Bad request, possibly due to missing or invalid parameters.
• 400 api_not_implemented：Bad request, possibly due to missing or invalid parameters.
• 401 invalid_token：Unauthorized, invalid or missing authorization token.
• 429 too_many_requests：Too many requests, you have exceeded the rate limit.
• 500 api_error：Internal server error, something went wrong on the server.

​

エラー応答例

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​

結論

本ドキュメントを通じて、Kling Videos Generation API を使用して、プロンプトおよび開始フレームの参照画像を入力することで動画を生成する方法をご理解いただけたかと思います。本ドキュメントが、本 API との連携および利用により役立つことを願っております。ご不明な点がございましたら、いつでも弊社の技術サポートチームまでお問い合わせください。

​

Kling 3.0 Turbo

model="kling-v3-turbo" はテキストからの動画生成および開始フレーム画像からの動画生成に対応しており、長さは 3～15 秒の整数です。mode="std" は 720p を出力し、mode="pro" は 1080p を出力します。このモデルにはネイティブ音声が搭載されており、無効化するスイッチは提供されていません。generate_audio は省略するか、true に設定してください。このモデルは終了フレーム、カメラワーク対象、独立したネガティブプロンプト、または cfg_scale をサポートしていません。必要な内容または表示を避ける内容は、prompt に直接記述してください。

​

マルチショット動画

kling-v3 と kling-v3-omni は multi_shot=true をサポートしています。shot_type="intelligence" は prompt に基づいて自動的に絵コンテを作成します。shot_type="customize" は multi_prompt を通じて 1～6 個のショットを提供し、各項目には 1 から連続して増加する index、最大 512 文字の prompt、および少なくとも 1 秒の整数の duration が含まれます。すべてのショットの長さの合計は、総 duration と等しくなければなりません。カスタムショットではグローバル prompt は使用されません。マルチショットは、選択したモデル、画質、音声設定、および総時間に基づいて課金されます。