mcpField
K
kling-advanced-lip-sync

kling-advanced-lip-sync

github.com/calesthioクリエイティブ・メディア21997 回インストール15 週間前に更新
リポジトリ

kling-advanced-lip-sync について

Kling AI Open Platform の Advanced Lip-Sync API で既存動画の発話を置き換えるためのワークフロースキルです。顔の選択、音声タイミング、タスク監視、出力確認を扱い、新たな話者映像を生成する方式とは区別しています。

主な機能

  1. 01映っている顔の検出と選択
  2. 02動画と音声入力の検証
  3. 03音声の切り出しと挿入時刻の設定
  4. 04リップシンクタスクの作成と監視
  5. 05同期、映像、ミックスの確認
  6. 06同意と出力の管理記録

活用シーン

  1. 01許可を得たインタビューの台詞をローカライズ
  2. 02複数人の映像で一人の発話を置き換え
  3. 03納品前にリップシンク結果を確認

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/calesthio/generative-media-skills --skill kling-advanced-lip-sync

インストール後、Claude Code で/kling-advanced-lip-syncを入力して読み込まれたか確認します。

同梱ファイルEVAL.md

詳細

Kling Advanced Lip-Sync

既存の動画に対して、Kling AI Open Platform の公式ドキュメントに記載された Advanced Lip-Sync ワークフローを使用する場合に、このスキルを使います。静止画像と音声から新しい会話パフォーマンスを生成する Avatar とは異なります。

検証と根拠

  • 公式ドキュメント記載の事実： Kling Open Platform の公式ページに記載されている動作です。
  • 実運用上のヒューリスティック： 実用的な同期・修復の推奨事項ですが、Kling による保証はありません。
  • 実証的な観察結果： 実際のタスク／出力から測定された結果です。

事実は 2026-07-12 に検証しました。エンドポイントの公開状況、利用資格、料金、コールバックの動作、データ保持、制限、ポリシーは変更される可能性があります。有料で使用する前に、公式ドキュメント、認証済みコンソール、アカウントのプラン、および適用される契約を再確認してください。

公式ワークフロー

現在の例で使用されているベース URL：

https://api-singapore.klingai.com

操作：

  1. POST /v1/videos/identify-face
  2. POST /v1/videos/advanced-lip-sync
  3. GET /v1/videos/advanced-lip-sync/{id}
  4. GET /v1/videos/advanced-lip-sync

ナビゲーション上でタブが Face Recognition と呼ばれている場合でも、操作名は Identify Face です。見えている顔を選択するための顔識別／検出として説明し、一般的な本人照合機能だと主張しないでください。

認証

公式ドキュメントでは、Kling Open Platform のアクセス／シークレット認証情報から生成される JWT Bearer 認証を使用します。

Authorization: Bearer ${KLING_JWT}
Content-Type: application/json

トークンの作成方法と有効期間については、最新の認証ページに従ってください。サーバー側で生成し、最小権限を適用してください。また、キー／シークレット／JWT をブラウザーコード、ログ、コールバック、フィクスチャに含めないでください。

動画ソースを検証する

Identify Face が受け付けるのは、次のいずれか1つだけです。

  • video_id：公式ドキュメントに記載された直近の期間内に Kling で生成された動画。
  • video_url：アクセス可能な外部動画。

この2つは相互に排他的です。

現在の外部動画の制約には、.mp4 または .mov、2～60秒、最大100 MB、720pまたは1080p、幅／高さそれぞれ512～2160ピクセルが含まれます。現在のドキュメントでは、Kling の video_id の有効期間も30日以内に制限されています。Kling はコンテンツを検証します。

事前に、コーデック／コンテナ、長さ、寸法、ファイルサイズ、URLへの到達可能性、音声の有無、顔の見えやすさ、カット、遮蔽、同意を確認してください。Kling がアクセスできない非公開 URL や、操作間に変更される可能性のある可変 URL をアップロードしないでください。

顔を識別して選択する

例：

POST /v1/videos/identify-face

{"video_url":"https://example.com/source.mp4"}

レスポンスには session_id と face_data[] が含まれます。各顔には、face_id、face_image、ミリ秒単位の start_time、end_time が含まれる場合があります。

検出された顔の切り抜き画像／区間を、ユーザーまたは権限を持つオペレーターに提示してください。複数の顔がある場合は、公式に記載され、承認された選択ルールがない限り、明示的に face_id を指定するよう求めてください。選択した顔、選択理由、区間を記録してください。

face_choose は配列ですが、現在のドキュメントでは1人のみのリップシンクに対応すると明記されています。複数の話者を同時に置き換えられると主張しないでください。ソース動画を編集した後は再識別してください。変更後のメディアに古いセッションを再利用しないでください。

検証済みのドキュメントでは、セッションの有効期限／再利用の仕様は公開されていません。Identify と Create を続けて実行し、無効なセッションは新しい識別ジョブとして処理してください。

音声とタイミングを準備する

選択した顔に対して、次のいずれかを必ず 1 つ指定します。

  • audio_id：最近の Kling TTS 音声。
  • sound_file：アクセス可能な URL または Base64 音声。

これらは相互に排他的です。

現在の外部音声の制約は、.mp3、.wav、.m4a、または .aac、長さ 2～60 秒、サイズ 5 MB 以下です。現在のドキュメントでは、audio_id の有効期間は 30 日以内に限られています。

タイミングフィールドの単位はミリ秒です。

  • sound_start_time：ソース音声の切り抜き開始位置。
  • sound_end_time：切り抜き終了位置。
  • sound_insert_time：ソース動画への挿入位置。

次の条件を検証します。

$$ cropDuration = soundEnd - soundStart \ge 2000\text{ ms} $$

切り抜き範囲はソース音声内に収まり、挿入範囲は動画内に収まっている必要があります。また、挿入範囲は選択した顔の検出区間と少なくとも 2 秒間重なる必要があります。

ミリ秒を使って明示的に計算してください。誤って秒を渡さないでください。

ミックスの制御項目：

  • sound_volume：現在のドキュメントに記載された範囲は 0～2、既定値は 1。
  • original_audio_volume：範囲は 0～2、既定値は 1。ソースが無音の場合は効果がありません。

必要に応じて環境音を残しつつ、ソースの会話によって音声が二重にならないようにしてください。リップモーションとは別に、最終ミックスを確認してください。

タスクを作成する

リクエストの例：

{
  "session_id": "<identify-face-session>",
  "face_choose": [
    {
      "face_id": "<approved-face-id>",
      "sound_file": "https://example.com/dialogue.wav",
      "sound_start_time": 0,
      "sound_end_time": 3000,
      "sound_insert_time": 1000,
      "sound_volume": 1,
      "original_audio_volume": 0.25
    }
  ],
  "external_task_id": "scene-014-take-03",
  "callback_url": "https://example.com/hooks/kling",
  "watermark_info": {"enabled": false}
}

これは、3 秒間の切り抜き、十分な動画の長さ、および選択した顔の区間との 2 秒以上の重なりを前提としています。

external_task_id の一意性は呼び出し元の責任です。これをシステムの task_id、ソース／音声のハッシュ、セッション／顔 ID、タイミング、音量、試行回数、同意記録、コストの事前確認とともに保存してください。

監視と照合

タスクのステータス：

  • submitted
  • processing
  • succeed
  • failed

単一タスクのエンドポイントを信頼できる情報源として使用してください。コールバックを使うとポーリングの遅延を減らせますが、本番環境での処理は冪等にし、重複イベントや順不同のイベントを受け入れる必要があります。現在のコールバックページに署名方式が記載されていない限り、独自の方式を作らないでください。コールバックのデータを信頼または公開する前に、タスクを取得してください。

一覧クエリでは現在のページネーション範囲を使用してください。タスク ID が分かっている場合は、一覧を走査しないでください。

一時的なレート制限、同時実行数、サーバーのエラーは、上限を設けたジッター付きの再試行を行ってください。認証、権限、パラメーター、ポリシー、無効なメディアに関するエラーは、変更せずに再試行しないでください。プロバイダーのコード、メッセージ、リクエスト ID を保持してください。

コスト、アクセス、結果の管理

検証時点では、公開料金ページから Advanced Lip-Sync 専用の料金は明確に確認できませんでした。Avatar の料金が適用されると想定しないでください。認証済みコンソール／パッケージの利用権を確認し、日付入りの予算承認を作成してください。

タスクが成功した際のレスポンスには最終的な差し引き項目が含まれます。実際の使用量／残高を見積もりと照合してください。

生成されたメディアは 30 日後に削除されると記載されています。速やかに管理されたストレージにダウンロードし、チェックサムを計算し、メディア情報を調べて、来歴を保持してください。プロバイダーの URL を永続的な配信用ストレージとして使用しないでください。

エンドポイントの利用権と同時実行数は、アカウント／パッケージによって異なります。レート制限、同時実行数、パッケージの上限超過、権限拒否などのエラーは、正確に提示してください。

同意、プライバシー、権利

このワークフローでは、認識可能な顔が映った動画と音声／声を処理します。以下を必須としてください。

  • 顔の類似性および音声／声に関する、明示的な権限の記録。
  • 使用目的、対象者、地域、期間、変更の範囲、同意の撤回、保持期間。
  • 未成年者、従業員、公人、政治的用途、故人、センシティブな状況に関する追加審査。
  • 欺瞞的ななりすましや、重要な改変を開示しない行為の禁止。
  • ソース動画、顔の切り抜き、音声、セッション、出力に対するアクセス制御と削除手順。
  • 必要に応じたプラットフォーム／法務上の開示と来歴情報。

Kling の技術的な face_id は、本人確認や同意の証明にはなりません。ホスティング、保存、転送、処理、モデル改善、エンタープライズ向け例外について、現在の API のプライバシー／利用規約を確認してください。トレーニング、データの保管場所、削除に関する無条件の主張はしないでください。

同期の確認と修復

Klingは、正式な同期品質指標や修復APIを公開していません。以下は、本番環境での経験則です。

  1. 破裂音、唇音、単語の開始、フレーズの終わりの前後を、通常速度とフレーム単位で確認します。
  2. 口の動きが、環境音ではなく発話に合わせて始まり、終わることを確認します。
  3. 挿入区間を通して、選択した顔が見えていることを確認します。
  4. 横顔、カット、遮蔽、口を覆う手、顔ひげ、モーションブラーを確認します。
  5. 顎、歯や舌、表情の固定、人物の同一性のずれ、周辺のピクセルを確認します。
  6. ミックスの変更後に、環境音の連続性と発話の重複を確認します。
  7. タイミングの修正は、まず再クロップまたは挿入時刻の変更で行います。
  8. 難しい区間は、クリップ全体を何度も処理するのではなく、短くします。
  9. 未変更のマスターを保存し、変更範囲外と比較します。

再実行すれば必ず出力が改善すると断言しないでください。変数を1つ変更して記録し、比較します。

例1：単一話者のローカライズ挿入

これは完全な例であり、必須の手順ではありません。

目的： 許可を得たインタビューの3秒間のセリフを置き換え、部屋の環境音を維持します。

12秒、1080p、100 MB未満のMP4を事前確認し、同意を得た話者が1人映っていることを確認したうえで、5 MB未満の3.2秒のWAVを用意します。顔を検出し、2〜10秒の区間をカバーする承認済みの顔を選択してから、音声を100〜3100 msでクロップし、3500 msの位置に挿入します。これにより、動画内に3000 msの挿入区間ができ、顔が映る区間内に少なくとも2秒収まります。環境音を保ちつつ、元のセリフが重ならないよう音量を十分に下げます。

タスクIDで進行状況を監視し、すぐにダウンロードしてチェックサムを確認してから、子音、動きの開始と終了、人物の同一性、遮蔽、環境音を確認します。同期の開始が遅れる場合は、音量変更や音声の再生成より先に、挿入位置やクロップを調整します。

例2：複数の顔が検出された場合

これは完全な例であり、必須の手順ではありません。

目的： 2人が出演するパネル動画で、司会者のセリフを1つ置き換えます。

Identify Faceで、異なるクロップと区間を持つ2つの顔が返されます。両方を提示し、許可を得た編集者が司会者を選択します。1人のリップシンクのみが文書化されているため、その顔について1つのタスクを作成し、ゲストも同時に置き換えられるとは約束しません。司会者が映り続け、ゲストが口を遮らない区間を選択します。環境音だけが残る場合は元の音声を維持し、それ以外の場合は準備済みのミックスを使用します。

両方の話者を置き換える要件になった場合は、文書化されていない複数顔のタスクを連結するのではなく、作業を中止して、別のサポート対象ワークフローを選択します。

出典

公式情報の確認日：2026-07-12：

コメント

Markdown 対応