TokenLabがVideo APIワークフロー向けにKling 3.0のElement Referencesを追加

靴と手を映す製品デモには、1つではなく2つの視覚的なアンカーが必要です。この度、ビデオ生成APIでKling 3.0の要素リファレンスをサポートしました。Kling 3.0の要素リファレンスAPIを使用すると、開発者は特定の製品、小道具、またはキャラクターを名前付きタグ（@name）に固定し、生成されたクリップ全体で一貫性を保つことができます。これは、1枚の参照画像だけでは複数の被写体をフレーム間で視覚的に安定させることができなかった、画像条件付きビデオワークフローのギャップを埋めるものです。

なぜマルチ被写体ビデオに要素リファレンスが必要なのか

1枚の参照画像は1つの被写体には有効ですが、シーン内で複数の異なる要素を維持する必要がある場合には機能しません。例えば、手で持たれた製品を表示する場合、製品と手の両方を安定させる必要があります。対話する2人のキャラクターには、顔と衣装それぞれの継続性が必要です。このギャップに対処するため、Kling 3.0の要素リファレンスをサポートしました。

重要なポイント

• Kling 3.0の要素リファレンスを使用すると、参照画像のURLを持つ名前付き要素を定義し、プロンプトテキスト内で直接タグ（@productA、@character1など）を使って呼び出すことができます。
• これは、製品とハンドモデル、キャラクターと小道具、対話シーンの2人のキャラクターなど、リクエストごとに1枚の参照画像では制限があったマルチ被写体シーンを対象としています。
• kling_elementsとoutput_audio=trueを同じリクエスト内で組み合わせないでください。現在のAPI仕様では、これら2つのパラメータは相互に排他的です。
• 要素リファレンスは、TokenLabの既存の他モデル向けリファレンス・トゥ・ビデオ（reference-to-video）サポートと並行して提供されます。これにより、開発者はユースケースごとに適切なアプローチを選択するための統一されたパターンを得ることができます。

Kling 3.0要素リファレンスAPIの仕組み

ほとんどの画像条件付きビデオ生成では、参照画像を単一のアンカーとして扱います。モデルに画像を与えると、モデルは周囲の動きをアニメーション化しながら、全体的な外観の一貫性を保とうとします。これは単一被写体のショットには有効ですが、シーン内で複数の視覚的に異なる要素を独立して維持する必要がある場合にはすぐに破綻します。

Kling 3.0の要素リファレンスは、1つのリクエスト内で複数の名前付き参照画像を登録できるようにすることで、この問題を解決します。プロンプトテキスト内から個別にそれらを指定します。暗黙的な参照が1つあるのではなく、明示的でアドレス指定可能な参照が得られます。モデルは、@shoeが参照画像1を指し、@modelが参照画像2を指していることを認識し、両方のアンカーを使用してシーンを構成します。

私たちは現在のAPI仕様においてこのパターンを確認しました。これは、製品ビデオパイプライン、キャラクター主導のコンテンツツール、広告クリエイティブジェネレーターにとって、制御能力を大きく向上させる一歩です。クリップ全体での被写体の一貫性は、多くの場合、実用的な出力と撮り直しの分かれ目となります。

リクエストでのKling 3.0要素リファレンスAPIの使用

パターンは単純です。要素を定義し、名前を付け、プロンプト内で@構文を使用して参照します。

{
  "model": "kling-3.0",
  "prompt": "@shoe rotates slowly on a marble pedestal while @hand reaches in to pick it up",
  "kling_elements": [
    {
      "name": "shoe",
      "image_url": "https://example.com/product-shoe.png"
    },
    {
      "name": "hand",
      "image_url": "https://example.com/hand-reference.png"
    }
  ],
  "duration": 5,
  "aspect_ratio": "16:9"
}

実装上の注意点：

• 要素名は短く、曖昧さのないものにしてください。プロンプトテキストに現れそうな一般的な英単語と重複する名前は避けてください。重複すると、解析の曖昧さが増す可能性があります。
• 参照画像のURLは、リクエスト時に公開アクセス可能である必要があります。画像が認証されたストレージ層の背後にある場合は、リクエストを送信する前に署名付きURLまたは公開URLを生成してください。
• 1つのプロンプトで複数の要素を組み合わせることはできますが、シーンの説明は絞り込んでください。2〜3個以上の名前付き要素を詰め込むと、各要素を個別に追跡するモデルの能力が低下する傾向があります。これは、静止画像のプロンプトで名前付き被写体が多すぎると、被写体ごとの忠実度が低下するのと同様です。
• まずは短い時間でテストしてください。要素の一貫性の問題が発生する場合、最初の数秒で現れます。10秒のフルレンダリングよりも、3秒のドラフトで確認する方が低コストです。

実装チェックリスト

Kling 3.0の要素リファレンスワークフローを本番環境にリリースする前に、以下を確認してください：

• 各要素に一意で曖昧さのない名前が付けられているか
• 参照画像のURLが公開アクセス可能で、処理中も安定しているか
• プロンプトテキストが各要素を@name構文で正しくタグ付けしているか
• kling_elementsが存在する場合にoutput_audioがtrueに設定されていないか
• リクエストのバリデーションが、APIに到達する前にオーディオと要素の競合をキャッチしているか
• フルレンダリングの前に短い時間でテストレンダリングを行っているか
• リクエストごとの名前付き要素の合計が、一貫性を保つために2〜3個に抑えられているか

唯一のルール：要素とオーディオの併用不可

この制約は迅速なプロトタイピング中に見落としがちです。kling_elementsとoutput_audio=trueは同じリクエスト内で使用できません。両方を送信した場合、リクエストは期待通りに処理されません。

ワークフローでマルチ要素の視覚的一貫性と生成されたオーディオの両方が必要な場合は、作業を2つのステップに分けてください。まず要素リファレンスを使用してビデオを生成し、次にオーディオ生成パスを別途実行して、ダウンストリームで出力を結合します。これは現在のKling 3.0統合におけるドキュメント化された制約であり、バグではありません。事後的に対処するエッジケースとしてではなく、リクエストバリデーションロジックに組み込んでください。

私たちのパイプラインでは、リクエストを送信する前にクライアント側でこの競合を検証しています。

Kling 3.0要素リファレンスAPIと他のビデオワークフローの比較

要素リファレンスは、TokenLabのビデオAPIを通じて利用可能な、成長を続けるリファレンス・トゥ・ビデオ機能セットの1つです。どれを選択すべきかを知っておくことが役立ちます：

ワークフロー	最適用途	参照数	備考
単一画像toビデオ	1枚の静止画の単純なアニメーション	1	SeedanceやPixVerse V6を含む、サポートされているほとんどのビデオモデルで動作
Kling 3.0要素リファレンス	独立した一貫性を必要とするマルチ被写体シーン	2-3個の名前付き要素	同じリクエスト内でのオーディオ生成は不可
スタイルまたはモーションリファレンス	視覚スタイルやカメラモーションパターンの適用	1つのスタイル参照 + プロンプト	一部のモデルで利用可能、モデルごとのドキュメントを確認
テキストのみのプロンプト	高速な反復、視覚的なアンカーが不要な場合	0	プロトタイプ作成が最も速いが、制御性は最も低い

製品デモジェネレーターを構築している場合、通常は要素リファレンスが適切な選択です。単一のヒーロー画像のアニメーションを行う場合は、単純な画像toビデオの方が高速で反復コストも安くなります。ビデオモデルをより広く比較しているチームは、2026年のAPI向けベストAIビデオモデルの分析から始めることができます。これには、Kling 3.0がVeo 3やその他のオプションと比べて、さまざまなユースケースでどのように位置付けられるかが網羅されています。

FAQ

1つのKling 3.0リクエストで2つ以上の要素リファレンスを使用できますか？

はい、APIは個数にハードキャップを設けていませんが、1つのシーンに名前付き要素を追加するほど、実用的な一貫性は低下する傾向があります。ほとんどの製品およびキャラクターのユースケースでは、2〜3個が妥当な実用上の制限です。

kling_elementsとoutput_audio=trueの両方を送信するとどうなりますか？

現在のKling 3.0統合ではこれら2つのパラメータは相互に排他的であるため、リクエストは正しく処理されません。無駄な呼び出しを避けるため、リクエストを送信する前にクライアント側でこの組み合わせを検証してください。

要素リファレンスのサポートはKling 3.0固有のものですか、それとも他のモデルでも利用できますか？

@nameタグを使用した名前付き要素リファレンスは、現在のAPIではKling 3.0固有のものです。サポートされている他のビデオモデルには、それぞれ独自のリファレンス・トゥ・ビデオパターンがあります。通常、リクエストごとに1つの参照画像に制限されているため、機能の同等性を前提とする前にモデル固有のドキュメントを確認してください。

ソース、鮮度、および関連資料

この記事は、2026年7月7日時点で観測されたTokenLabビデオAPIドキュメントおよびKling 3.0統合の動作を反映しています。現在のパラメータリファレンスについては、ビデオ作成APIリファレンスおよびビデオ生成ガイドを参照してください。APIの動作は変更される可能性があるため、本番環境の統合を完了する前に必ずライブドキュメントを確認してください。

要素リファレンスはKling 3.0で可能なことを拡大しますが、本番ワークフローを構築する前には、適切なビデオモデルの選択とコストの理解が依然として重要です。オプションを比較している場合は、ベストAIビデオモデルAPIガイド：開発者がビデオ生成モデルを選択する方法で、プロバイダー間のトレードオフを確認してください。Klingの詳細については、Kling AI API料金ガイド：コスト、ワークフロー、および代替案で、価格とワークフローの考慮事項を解説しています。また、代替案を検討している場合は、Seedance APIガイド：AIビデオ生成にいつ使用すべきかで、そのモデルが適している場合をカバーしています。

モデルの機能と価格は頻繁に変更されるため、大量の本番利用に依存する前に、現在のモデルバージョンと料金を直接確認してください。アカウント設定リファレンスでAPIキーの作成方法を説明しています。

マルチ被写体ビデオワークフローの構築を開始するには、TokenLab APIキーを取得し、ビデオ生成ガイドを確認してください。