kling-official

Kling 公式 Direct API

provider="kling_official" を指定する OpenMontage ツールで使用します。これは fal.ai の Kling ゲートウェイではありません。公式 Kling では KLING_API_KEY、任意の KLING_API_BASE_URL、および Authorization: Bearer <KLING_API_KEY> を使用します。

プロバイダーの使い分け

• kling_video は fal.ai、FAL_KEY、fal.ai のキュー URL、および provider="kling" を使用します。
• kling_official_video は公式 Kling API、KLING_API_KEY、公式タスクプロトコル、および provider="kling_official" を使用します。
• kling_official_image は、画像生成に同じ公式認証とタスクプロトコルを使用します。
• kling_tts は公式オーディオ TTS エンドポイントを使用し、既存の tts 機能にとどまります。
• kling_avatar と kling_lip_sync は公式アバター／リップシンクエンドポイントを使用し、既存の avatar 機能にとどまります。ローカルの talking_head や lip_sync を置き換えるものではありません。

これらの経路を、明示せずに切り替えてはいけません。選択したプロバイダーを利用できない場合は、問題点を示し、代替手段に切り替える前にユーザーに確認してください。

認証とエンドポイント

デフォルトのベース URL：

https://api-singapore.klingai.com

ユーザーは、地域別エンドポイントなどを指定するために KLING_API_BASE_URL で上書きできます。すべてのリクエストでは JSON と以下を送信します。

Authorization: Bearer <KLING_API_KEY>

タスクプロトコル

Classic API：

• 作成 ID のパス：data.task_id
• ステータス：submitted、processing、succeed、failed
• 結果のパス：data.task_result.videos[]、data.task_result.images[]、data.task_result.audios[]

Turbo API：

• 作成 ID のパス：data.id
• ポーリングパス：GET /tasks?task_ids=<id>
• ステータス：submitted、processing、succeeded、failed
• 結果のパス：data[0].outputs[]

パーサーは分けたままにしてください。task_id と id、または succeed と succeeded のどちらかを推測する曖昧なパーサーを作成してはいけません。

Omni の参照

Video Omni と Image Omni は、api_family="omni" を通じて既存のプロバイダーツール内にとどまります。 セレクターレベルの Omni 操作は作成しないでください。

Video Omni は、公式の参照構造を受け付けます。

• image_url と、first_frame や end_frame などの任意の type を含む image_list[]。
• video_url、feature や base などの公式 refer_type 値、および任意の keep_original_sound を含む video_list[]。
• 公式 element_id 値を含む element_list[]。
• 構造化された multi_prompt[]。自然言語を自動的にショットに分割しないでください。

ローカルの画像参照は tools/_kling/media.py を通じて正規化できます。ローカルの動画パスを、ユーザーに知らせず fal.ai 経由でアップロードしてはいけません。アクセス可能な URL をユーザーに尋ねるか、必須としてください。

Image Omni は、公式の image 値を含む image_list[] を受け付けます。<<<image_1>>> などのプロンプト内プレースホルダーは、指定された画像の順序に安定して対応付ける必要があります。プロンプトにすでにプレースホルダーが含まれている場合は、参照先の画像が存在することを検証し、重複を挿入しないでください。

機能の境界

TTS、アバター、リップシンクは、既存の OpenMontage 機能にプロバイダーを追加するものです。オーディオエフェクトとビデオエフェクトは公式 Kling エンドポイントですが、それらを受け入れる安定した機能スロットがパイプラインに用意されるまでは、デフォルトの OpenMontage ツールとして登録されません。

• プロバイダー実装内から sound_effects や video_effects の機能を追加しないでください。
• ビデオエフェクトを通常の video_generation セレクターパスに含めないでください。
• パイプラインがその形式を明示的に利用し、ツールの best_for／not_good_for がそれを示している場合を除き、短い効果音を長いバックグラウンドミュージックとして扱わないでください。

動画パラメーター

OpenMontage のセマンティクスには operation を使用します。

• text_to_video
• image_to_video
• reference_to_video

公式プロトコルの選択には api_family を使用します。

• classic
• turbo
• omni

重要な制約：

• 公式動画プロバイダーの入力スキーマでは、トップレベルの image_url を公開しないでください。reference_image_url または reference_image_path を使用してください。
• Classic の image-to-video では、reference_image_url または公式フィールド image に raw base64 として変換したローカルパスを受け付けます。
• Turbo の image-to-video では、最初のフレームに URL が必要です。フォールバックとして fal.ai 経由でローカルファイルをアップロードしないでください。
• aspect_ratio は、現在のスキーマがサポートする場合にのみ送信してください。対象は Classic の text-to-video、Turbo の text-to-video、Video Omni です。
• 明示的に選択されていない限り、デフォルトの有料パスでは 4k、ネイティブサウンド、バッチ処理を避けてください。

画像パラメーター

/v1/images/generations には api_family="generation" を、/v1/images/omni-image には api_family="omni" を使用します。

生成／編集パス：

• prompt は必須で、公式の上限である 2500 文字以内にしてください。
• image_url は公式の image にそのまま渡されます。
• image_path は raw base64 に変換され、公式の image として送信されます。
• image_reference には subject または face を指定できます。

Omni パス：

• 参照画像は、公式の image 値を使用して image_list[] に配置してください。
• 特定の参照画像をプロンプトに紐付ける必要がある場合に限り、<<<image_1>>> などのプロンプトプレースホルダーを使用してください。

TTS パラメーター

kling_tts では以下を使用します。

• text
• voice_id
• voice_language。現在は zh または en
• voice_speed

公式アカウント固有のデフォルト値が確認されていない限り、明示的な voice_id を必須にしてください。存在しない音声をハードコードしないでください。返された音声アイテムをすべてダウンロードし、最初のローカルファイルを data.output_path に設定してください。また、voice_id、voice_language、voice_speed、task_id、およびゼロ以外の cost_usd を含めてください。

アバターパラメーター

kling_avatar は /v1/videos/avatar/image2video を使用し、以下を受け付けます。

• URL、または raw base64 に変換したローカルパスによるアバター画像
• audio_id または sound_file
• 任意の prompt
• std や pro などの mode

ローカルの talking_head とは分けてください。Kling アバターの出力を使用するパイプラインでは、明示的に列挙して選択する必要があります。

リップシンクパラメーター

kling_lip_sync には 2 つのステップがあります。

1. video_id または video_url を指定して POST /v1/videos/identify-face を呼び出し、data.face_data[] から顔を読み取ります
2. session_id と、face_id、audio_id または sound_file、およびサウンドの開始／終了／挿入時刻を含む face_choose[] の項目 1 つを指定して POST /v1/videos/advanced-lip-sync を呼び出します

ローカル動画パスを fal.ai やその他のプロバイダー経由で、暗黙的にアップロードしてはなりません。複数の顔が返され、ユーザーが face_id または face_choose を指定していない場合は、auto_select_face=True が明示的に設定されていない限り処理を中断し、確認のため顔の一覧を返してください。自動選択する場合は、選択理由と選択した顔を結果／アーティファクトに記録してください。

オーディオエフェクトとビデオエフェクト

公式の Kling オーディオエフェクト（/v1/audio/text-to-audio、/v1/audio/video-to-audio）とビデオエフェクト（/v1/videos/effects）は、意図的にデフォルトの OpenMontage セレクターツールから除外されています。現在のパイプラインで誤用される可能性のあるツールを登録するのではなく、マッピングしない理由を docs/tests に記録してください。

Elements ヘルパー

Elements は内部的な Kling Official ヘルパーであり、新しい OpenMontage ツール機能ではありません。 tools/_kling/elements.py を使用して element_list[].element_id を正規化し、必要に応じて読み取り専用の要素エンドポイントに問い合わせ、問い合わせた場合は要素メタデータを記録してください。デフォルトのプロバイダーパスでは、要素を作成または削除しないでください。

アカウント使用状況ヘルパー

アカウント使用状況の確認は診断専用です。ローカルキャッシュとスロットル保護を備えた tools/_kling/account.py を使用して、低頻度で /account/costs を確認してください。生成のたびに呼び出したり、セレクターや本番パイプラインのステージに含めたりしないでください。

1101 または 1102 の場合は、アカウントまたはリソースパックが枯渇していることを示し、アカウント使用状況の診断に関するヒントを含めてください。

コールバックに関する注意事項

プロバイダーはcallback_urlを受け付ける場合がありますが、デフォルトの実行モードは引き続きポーリングです。

• Classic と Omni のパスでは、callback_urlをトップレベルに渡します。
• Turbo のパスでは、options.callback_urlとして渡します。
• 成功した結果には、callback_requested=true、polling_used=true、callback_url、およびtask_idを記録してください。
• 送信前にコールバック URL を検証してください。絶対 URL で、httpまたはhttpsのみを受け付けてください。

エラー処理

公式のcode、message、およびrequest_idが利用可能な場合は、必ず提示してください。

以下の場合は再試行しないでください。

• 認証エラー：1000～1004
• 残高／リソースパックの枯渇：1101、1102
• 権限／モデルへのアクセス：1103
• パラメーターエラー：1200、1201
• 安全ポリシー：1301

以下の場合は、回数を制限した再試行が許容されます。

• 1302 リクエストが速すぎます
• 1303 同時実行数／リソースパックのスロット上限
• 5000、5001、5002 サーバー／メンテナンス／バックログのエラー

1303の場合は、アカウントが同時実行数またはリソースパックのスロット上限に達したことを説明してください。

コスト管理

公式の Kling は有料のリモート API です。プロバイダーのツールは、estimate_cost()でゼロ以外の保守的な見積もりを返し、支払いが発生する処理の成功結果にはcost_usdを含める必要があります。アカウント使用量との照合が実装されるまでは、見積もりの信頼度は低いものとして扱ってください。 複数の参照、要素 ID、result_type="series"、mode="4k"、sound="on"など、コストの高い Omni 入力では、コスト見積もりを増やすか、注意を促してください。

プロンプトに関する注意事項

動画では、汎用的な OpenMontage 動画プロンプトのひな形（被写体、被写体の動き、シーン、空間的なフレーミング、カメラ）から始めてください。Kling は、明確な時間順のアクション、カメラの動きを表す動詞、簡潔なネガティブプロンプトに適切に応答する傾向があります。参照を使うワークフローでは、参照から維持する要素と変更する要素を明示してください。