Kling Videos Generation API 接続説明

本稿では、カスタムパラメータを入力してKling公式の動画を生成できるKling Videos Generation APIの接続方法について説明します。

申請手順

APIを使用するには、まず Kling Videos Generation API の該当ページでサービスを申請する必要があります。ページにアクセスしたら、「Acquire」ボタンをクリックします。以下の図のように表示されます：

ログインまたは登録していない場合は、自動的にログインページにリダイレクトされ、登録・ログイン後に元のページに戻ります。初回申請時には無料枠が付与され、このAPIを無料で利用可能です。

基本的な使い方

まず基本的な使い方を理解しましょう。入力するのはプロンプト prompt、生成動作 action、初期フレームの参照画像URL 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-video-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-video-o1。
mode：動画生成モード。標準モード std、高速モード pro、ネイティブ4Kモード 4k。4k は kling-v3 と kling-v3-omni のみ対応し、camera_control（カメラ操作）とは非互換。
action：動画生成タスクの動作。テキストから動画生成（text2video）、画像から動画生成（image2video）、動画拡張（extend）。
start_image_url：image2video 動作時に必須の初期フレーム参照画像URL。
end_image_url：image2video 時のオプションで、終了フレーム指定。
duration：動画の長さ（秒）。kling-v3 と kling-v3-omni は3～15秒（整数）に対応、その他モデルは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文字。
element_list：主体参照リスト。モデル kling-video-o1 のみ対応。詳細は公式ドキュメント参照。
video_list：参照動画。URL経由で取得。モデル kling-video-o1 のみ対応。詳細は公式ドキュメント参照。
prompt：プロンプト。
callback_url：結果コールバック用URL。

選択すると右側に対応するコードが生成されます。以下の図の通りです：

「Try」ボタンをクリックするとテストを実行できます。上図のように以下の結果が得られます：

{
  "success": true,
  "video_id": "af9a1af0-9aa0-4638-81c1-d41d6143c508",
  "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7485378259/text2video/Cjil4mfBfs0AAAAAAKbMQQ-0_raw_video_1.mp4",
  "duration": "5.1",
  "state": "succeed",
  "task_id": "e3a575aa-a4bd-49c8-9b12-cde38d5462e0"
}

返却されるフィールドは以下の通りです：

success：動画生成タスクの状態。
task_id：動画生成タスクID。
video_id：動画生成タスクの動画ID。
video_url：動画生成タスクの動画URL。
duration：動画の長さ。
state：動画生成タスクの状態。

満足のいく動画情報が得られたら、data 内の動画URLから生成されたKling動画を取得できます。また、対応する接続コードを生成したい場合は、直接コピー可能です。例えばCURLコードは以下の通りです：

curl -X POST 'https://api.xhuoapi.ai/v1/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-v1",
  "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-video-o1`	std / pro	✅	❌	❌	`duration=5/10` のみ対応

注意点：

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 を受け入れる。その他モデルは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 動作時に必須の初期フレーム参照画像URL。
prompt：プロンプト。

入力例は以下の通りです：

入力完了後、自動で以下のコードが生成されます：

対応するPythonコード：

import requests

url = "https://api.xhuoapi.ai/v1/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.klingai.com/bs2/upload-kling-api/7822108635/extendVideo/Cjil4mfBfs0AAAAAAKhr6A-0_raw_video_1.mp4",
  "duration": "9.6",
  "state": "succeed",
  "task_id": "3ece87e6-3ee3-4f5e-bd70-5ae5eca89a23"
}

結果は前述と同様で、動画の拡張機能が実現されています。

非同期コールバック

Kling Videos Generation APIの生成時間は比較的長く、約1～2分かかります。APIが長時間応答しない場合、HTTPリクエストは接続を維持し続け、システムリソースを余計に消費します。そこで本APIは非同期コールバックをサポートしています。全体の流れは、クライアントがリクエスト時に callback_url フィールドを追加指定します。APIは即座に 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.klingai.com/bs2/upload-kling-api/7822108635/text2video/CjJzzGfBfqcAAAAAAKdVMQ-0_raw_video_1.mp4",
    "duration": "5.1",
    "state": "succeed",
    "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}

結果に task_id フィールドがあり、他のフィールドも前述と同様です。このIDでタスクを関連付けられます。

エラー処理

API呼び出し時にエラーが発生した場合、APIは対応するエラーコードとメッセージを返します。例：

400 token_mismatched：不正なリクエスト。パラメータ不足や不正の可能性。
400 api_not_implemented：不正なリクエスト。パラメータ不足や不正の可能性。
401 invalid_token：認証エラー。無効または欠落した認証トークン。
429 too_many_requests：リクエスト過多。レート制限超過。
500 api_error：サーバー内部エラー。

エラー応答例

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

まとめ

本ドキュメントを通じて、Kling Videos Generation APIの使い方、プロンプトや初期フレーム参照画像を入力して動画を生成する方法を理解いただけました。本ドキュメントがAPIの接続と利用に役立つことを願っています。ご不明点があれば、いつでも技術サポートチームまでお問い合わせください。

Documentation Index

​申請手順

​基本的な使い方

​モデル能力マトリックス

​動画拡張機能

​非同期コールバック

​エラー処理

​エラー応答例

​まとめ