KlingのAPIをほかのAIやアプリから呼ぶ手順（その2）：4.0のエンドポイント、タスクの流れ、コールバックと署名の検証、同時実行、残量の確認、外し方

この記事は、公式の資料を2026年10月25日に読んでまとめたものです。この記事は、実際に使って確かめた記録ではありません。運営者はKlingを入れていますが、使い心地はこの記事には書いていません。手順は「公式の手順を順に並べたもの」です。コマンドは、公式の例を要約の形で読んだものから拾ったか、この記事で組んだ例（動作は確かめていません）です。署名を検証するコードは、公式のページの原文を見て組んでください。

先に結論

• 公式のAPIは、「作成してIDをもらい、あとで結果を引く」非同期の形。 作成の返事は submitted で、succeeded か failed になるのを、問い合わせるか、通知で知ります。
• モデルごとにURLの形が違う。 4.0は /text-to-video/kling-4.0 のように、モデルがURLの中にある新しい形式です。Kling 3.0 Omni以前は、model_name を本文に書く旧形式と、公式が書いています。
• 参考素材は contents に集める。 Omniには image_list や element_list のような別々の欄は無い、と公式が書いています。
• 署名の検証は任意。 有効にしなければ、既存のコールバックはそのまま動く、と更新履歴が書いています。
• お金の確認は、無料の GET /account/costs。

前提：用語をそろえる

• 非同期：依頼を出したあと、結果がすぐには返らず、あとで受け取る仕組みです。
• タスク：1回の生成の依頼です。IDがつきます。
• ポーリング：結果が出たかを、一定の間隔で問い合わせることです。
• コールバック（Webhook）：タスクの状態が変わったとき、Klingが、あなたが指定したURLにデータを送る仕組みです。
• HMAC-SHA256：秘密の値を使って、データの「署名」を作る方法です。受け取った側が同じ計算をして、一致すれば、送り主が秘密を知っている相手だと分かります。
• Base64：画像などの中身を、文字列にして送る書き方です。URLの代わりに使えます。
• カーソル：一覧の続きを取るための目印です。
• QPS：1秒あたりのリクエストの数です。

手順1：呼ぶ側の準備

1. 05の手順で、APIキーを作る。
2. 接続先は https://api-singapore.klingai.com。
3. すべてのリクエストに、Content-Type: application/json と Authorization: Bearer <キー> を付ける。
4. キーは、環境変数などに入れて、コードやチャットに書き込まない（公式が、漏れると他人が利用枠を使えてしまう、と書く点）。
5. APIの有料サービス規約は、キーを第三者に譲渡・貸与・開示・漏えいしてはならない、許可のない使用や安全上の問題に気づいたらすぐに通知する、と書いています（キーの下の活動の責任の扱いは、原文で確認してください）。

手順2：主なエンドポイント（公式のAPI資料）

• 公式の更新履歴によると、2026年7月15日に、Kling 3.0、3.0 Omni、3.0 Motion Control、2.6、2.6 Motion Control、2.5 Turbo が、ID・カーソルでの一括問い合わせができる新しいAPIに対応しました。旧APIも使え、廃止の予定は今のところない、と書かれています。
• 2026年6月17日の更新履歴は、APIキーだけでの認証が使え、AccessKey／SecretKeyと併用できる、と書いています。3.0 TurboのAPIはAPIキーだけです。

手順3：作成から結果の受け取りまで

3-1：作成する（4.0 の画像から動画）

公式の例は、contents に文章と画像を入れる形です。次は、公式の例の項目に合わせた、この記事で組んだ例です（動作は確かめていません）。

curl --location 'https://api-singapore.klingai.com/image-to-video/kling-4.0' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${KLING_API_KEY}" \
  --data '{
    "contents": [
      {"type": "prompt", "text": "A cat walks across a windowsill at dusk."},
      {"type": "first_frame", "url": "https://example.com/cat.png"}
    ],
    "settings": {"resolution": "720p", "duration": 5},
    "options": {"external_task_id": "my-task-0001"}
  }'

• options.external_task_id は、自分でつけるID。アカウントの中で重複しない、と公式が書いています。システムが出すIDを置き換えず、問い合わせに使えます。
• 返事の data.id がタスクのID、data.status が状態です。
• 画像の条件は、.jpg、.jpeg、.png、1枚30MBまで、各辺300px以上、比率2:5〜5:2、最大10枚。URLでもBase64でもよい、と公式が書いています。
• 長さは3〜30秒。指定しない場合、プロンプトに書いた長さの意図を読み、無ければ10秒、と公式が書いています。

3-2：Omniに素材を渡す

• 上限（公式）。 画像・動画・エレメント・声を合わせて15個まで。動画は.mp4か.mov、300MBまで、各3〜30秒、合計30秒。参考動画は最大5本で、編集の対象（base_video）は最大1本。エレメントは最大7個（動画エレメントは3個まで）。声は最大3個。
• 呼び方。 素材に id（例：image_1）をつけ、文章で @image_1 と書く。声の id が "1" なら @1。id は、1つのタスクの中で重複させない。素材の役割を文章で書く、と公式が書いています。複数の middle_frame や refer_image では、id が必須です。
• 画面比。 21:9、16:9、9:16、1:1、adaptive（既定）。adaptive は、プロンプトに書かれた比率、編集する動画（base_video）、キーフレームの画像、そのほかの入力動画の順に読み、どれも無ければ16:9にする、と公式が書いています。比率を明示すれば、それが優先されます。
• 声の voice_id は、声の管理API（/v1/general/custom-voices）か、システムの用意した声から得ます。エレメントの element_id は、エレメントのAPIから得ます。

3-3：結果を引く

curl --location 'https://api-singapore.klingai.com/tasks?task_ids=<タスクID>' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${KLING_API_KEY}"

• data[].status が succeeded になると、outputs に、動画の url、watermark_url、duration が入ります。failed のときは message に理由が入る、と公式が書いています。
• task_ids と external_task_ids は、どちらか一方だけを使います。コンマで区切って、複数を一度に引けます。
• 期間とカーソルで引くときは POST /tasks です。limit の既定は100、上限は500。cursor を使うと、時刻の指定は無視されます。絞り込みは status と product_type（video、image、try_on）です。
• 結果のURLは30日で消える、と公式が書いています。
• 問い合わせは、同時実行の枠を使いません。QPSの制限もない、と公式の同時実行ルールが書いています。

手順4：コールバックを受ける

4-1：URLを付けて、形を知る

1. 作成のとき、options.callback_url に、受け取るURLを書く（画像、動画、バーチャル試着の非同期のタスクが対象、と公式が書く）。
2. タスクの状態が変わると、そのURLに通知が来る。

通知の形が2種類あります。

• 失敗した通知の再送の方針は、公式のページに書かれていませんでした。
• 結果のURLは30日で消えます。通知を受けたら、早めに保存してください。

4-2：送り主を確かめる（署名の検証）

公式のコールバック資料が書いている内容です。署名を有効にした場合、通知に3つのヘッダーが付きます。

• 検証には、コンソールの「Webhook Secret」を使います。APIキーとは別のものです。公式は、コンソールの Basic Settings の Webhook で作る、と書いています（手元の画面と照らしてください）。署名のヘッダーは、Webhook Secret があるときだけ付く、と書かれています。
• 署名の対象は {webhook-id}.{webhook-timestamp}.{rawBody}（受け取った本文の生のまま）。HMAC-SHA256で署名し、鍵は、秘密から whsec_ を取ってBase64で戻したものです。比較は、時間が一定になる方法で行う、と書かれています。公式のSDKか、Standard Webhooks のライブラリを使うことを、公式は recommended と書いています。
• コードの全文は、公式のページで原文を見て組んでください。この記事には写しません。
• 公式の更新履歴（2026年8月7日）は、署名を有効にしなければ、既存のコールバックの連携は変更不要、と書いています。コールバック資料は、別の有効化のスイッチは説明されておらず、Webhook Secret を作ると署名が有効になり、秘密をすべて削除すると無効になる、と読める書き方です（原文で確認してください）。

4-3：テスト送信

• コンソールの Webhook のタブにある「Send Test Callback」で、callback_url を入れて、受け取り側を確かめられます。6秒に1回まで。成功はHTTP 200を返すこと、と公式が書いています。
• テストの本文は、status が submitted で、outputs が空の配列、message が空の文字列です。

手順5：同時実行と再送

• 同時実行は、アカウント・モデルのバージョン・パッケージの種類（動画か画像）ごとに数えます。同じアカウントのすべてのAPIキーが、同じ枠を共有します。
• 枠は、有効な同種のパッケージのうち、いちばん大きい値になります（5と10なら10）。
• タスクは、submitted になってから終わる（失敗を含む）まで枠を使います。動画とバーチャル試着は1つ、画像は n の数だけです。
• 超えると、code: 1303、parallel task over resource pack limit が返ります。公式は、指数的に待ち時間を伸ばして再送する（最初は1秒以上）、自前の待ち行列で出す速さを調整する、の2つを recommended と書いています。

手順6：使った量を確かめる

1. 残量の一覧。 GET /account/costs（05）。呼ぶのは無料、毎秒1回まで。
2. 明細。 公式の更新履歴は、2026年7月6日に、リソースパッケージと残高の引き落とし明細をAPIで書き出せるようにした、と書いています。公式のAPI資料に、「Balance Deduction Detail」「Unit Deduction Detail」のページがあります（本文は読んでいません）。
3. コンソール。 呼び出し量、パッケージの消費、単位ごとと残高ごとの明細（05）。
4. タスクごとの billing。 問い合わせの返事に、charge_type（cash か unit）、amount、currency、list_price などが入ります。

手順7：ほかのエンドポイントの要点

• エレメント。 作成は element_name（20文字まで）、element_description（100文字まで）、reference_type（image_refer か video_refer）が必須。画像は、正面の1枚と、別の角度の1〜3枚。動画は3〜8秒、1080p、最大200MB、実写の人物のみ。声は element_voice_id で結びつけられる。削除は POST /v1/general/delete-advanced-elements（公式は、カスタムのエレメントだけが対象、と書く）。
• 声。 作成は voice_name（20文字まで）と、voice_url か video_id のどちらか。音声は.mp3か.wav、動画は.mp4か.mov、5〜30秒、雑音がなく人の声が1つ。削除は POST /v1/general/delete-voices。
• モーションコントロール 3.0。 settings.character_orientation（image か video）が必須。参考動画は3秒以上で、video なら30秒まで、image なら10秒まで。エレメントは1タスクに1個まで。
• 画像。 prompt は2,500文字まで、n は1〜9、resolution は 1k か 2k。

渡るデータ

• APIの規約の「学習に使わない」は、Webの利用規約（04で扱った、入力を学習に使う許諾を含む書き方）とは書き方が違って見えます。どの規約がどの利用に及ぶかは、公式の資料だけでは確定できませんでした。
• 出力の知的財産の扱いは、適用される法律による、商用利用の侵害のリスクは利用者が負う、とAPIの有料サービス規約が書いています。
• 保存期間の日数は、プライバシーポリシーに固定の期間は書かれていません。削除の依頼先は enterprise@kling.ai と書かれています。

外し方

この記事の案（公式の手順ではありません）

以下は、公式の記載に合わせて、この記事で考えた案です。動作は確かめていません。

1. キーを用途ごとに分ける。 公式は、キーに名前をつけて複数作れる、と書いています。ただし、同時実行の枠は、同じアカウントのキーで共有されます。用途ごとに名前を分けておくと、どれを入れ替えるか、見分けやすくなります。
2. AIには、キーそのものでなく、実行できる範囲を渡す。 AIエージェントにキーを渡すと、キーの下の活動の責任は利用者にある、という規約の扱いになります。環境変数に入れ、チャットにキーを貼らない形にする、という考え方があり得ます。
3. 作成と回収を分ける。 AIが依頼を作り、external_task_id をつけ、callback_url で結果を別のプログラムに集め、30日の期限の前に保存する。AIには、結果のURLだけを返す。
4. 1つずつ、費用を見ながら。 最初は、最短の長さと低い解像度で1本出し、billing と /account/costs で減り方を見てから、まとめて頼む。

うまくいかないとき

気をつけること

• この記事は、実際に使って確かめた記録ではありません。運営者はKlingを入れていますが、使い心地はこの記事には書いていません。公式のAPI資料を読んだ範囲です。
• コマンドは、要約の形で読んだ公式のページから拾ったものと、この記事で組んだ例です。実行の前に、各ページの原文と照らしてください。署名の検証コードは、公式の原文を見て組んでください。
• 4.0のText-to-VideoのAPIページは、解像度を720pと1080pと書いています。Webのガイドと能力表は4Kにも触れています。公式ページ同士で違うので、使う前に確かめてください。
• モデルごとに、URLの形、model_name の有無、状態の綴り（succeeded と succeed）が違います。
• 公式のAPIの料金のページとパッケージの内容は、この記事では書いていません。金額は画面で確かめてください。
• 公式のAPIの規約と、Webの利用規約は、別のものです。データの扱いは、使う入口の規約を読んでください。
• 02の機能の説明は、Webのガイドの数字（4.0の3〜30秒など）です。APIで選べる値は、各APIページの値を優先してください。

出典

• Quick Start（Kling API ドキュメント、確認日 2026-10-25）
• Authentication（Kling API ドキュメント、確認日 2026-10-25）
• Error Codes（Kling API ドキュメント、確認日 2026-10-25）
• Concurrency Rules（Kling API ドキュメント、確認日 2026-10-25）
• Callback Protocol（Kling API ドキュメント、確認日 2026-10-25）
• Kling 4.0 Text to Video（Kling API ドキュメント、確認日 2026-10-25）
• Kling 4.0 Image to Video（Kling API ドキュメント、確認日 2026-10-25）
• Kling 4.0 Omni Video Generation（Kling API ドキュメント、確認日 2026-10-25）
• Kling 4.0 Element Management（Kling API ドキュメント、確認日 2026-10-25）
• Kling 4.0 Voice Management（Kling API ドキュメント、確認日 2026-10-25）
• Motion Control 3.0（Kling API ドキュメント、確認日 2026-10-25）
• Kling Image 3.0 & 3.0 Omni - Image Generation（Kling API ドキュメント、確認日 2026-10-25）
• Account Usage（Kling API ドキュメント、確認日 2026-10-25）
• API Updates（Kling API ドキュメント、確認日 2026-10-25）
• Terms of API Paid Service（Kling API ドキュメント、確認日 2026-10-25）
• Privacy Policy of API Service（Kling API ドキュメント、確認日 2026-10-25）
• Capability Map - Video（Kling API ドキュメント、確認日 2026-10-25）
• Kling API ドキュメント 目次（llms.txt、確認日 2026-10-25）