PixVerse リップシンク API チュートリアル：アップロード、生成、ポーリング、およびレビュー

AI Overview

PixVerse のリップシンク API には何が必要ですか？

1 つの動画参照と 1 つの音声ソースを提供します。動画は、PixVerse が生成した source_video_id またはアップロード済みの video_media_id のいずれかで構いません。音声は、アップロード済みの音声ファイル、あるいは TTS のスピーカーとスクリプトの組み合わせで構いません。

どのエンドポイントでリップシンクタスクを作成しますか？

API キー、新しいトレース ID、および有効な動画／音声の組み合わせを含む POST /openapi/v2/video/lip_sync/generate を送信します。タスクが正常に作成されると、完成済みのファイルではなく video_id が応答として返されます。

結果が準備できたタイミングはどのように確認しますか？

返された video_id を用いて GET /openapi/v2/video/result/{id} をポーリングします。PixVerse ではステータス 5 を「生成中」、ステータス 1 を「成功」と定義しており、ステータスが 1 になった時点で返された動画 URL を使用できます。

音声ファイルの代わりにテキストを使用できますか？

はい。組み込みまたはカスタムの TTS スピーカーを選択し、lip_sync_tts_speaker_id と lip_sync_tts_content を送信します。このルートと無関係な音声メディア ID を同一のリクエスト例で併用しないでください。

API 呼び出し前に動画と音声を選びましょう

本 PixVerse リップシンク API チュートリアルは、特定のタスクを対象としています：既存の動きのある顔に選択したセリフを合成し、非同期で返される結果を取得して、口の動きが実用的かどうかを判断するというものです。まずベースとなるクリップを作成する必要がある場合は、高速カットや横顔から正面への回転、手で顔が隠れるようなシーンよりも、短いスピーカーのショットの方が評価しやすくなります。そのベースクリップは、画像から動画へ変換するワークフロー、PixVerse による生成、または利用権を有する実際の映像素材で作成できます。

PixVerse 公式の「Speech ガイド」では、映像を提供する方法として 2 通りを明記しています。API によって作成されたクリップにはすでに video_id が付与されており、これを source_video_id として渡します。外部から入手したクリップはメディアエンドポイント経由でアップロードし、返される media_id を video_media_id として渡します。これらの ID は相互に交換できません。後続の再試行時に誤って生成済み動画フィールドにアップロード済みメディア番号を送信しないよう、自身のジョブログに各 ID の出所を明記してください。

音声については、audio_media_id を用いた完成済み録音ファイルの使用か、lip_sync_tts_speaker_id と lip_sync_tts_content を用いたテキスト・ツー・スピーチ（TTS）方式のいずれかを選択します。この 4 つの組み合わせ（生成 or アップロード動画 × 録音音声 or TTS）は、2×2 のマトリクスで表せます。カスタムスピーカー作成に使った音声サンプルは、リップシンクジョブで最終的にアップロードする音声とは役割が異なります。両者ともメディアアップロードステップを経る点は同じですが、目的は異なります。

以下の静止画は、架空の成人プレゼンターを題材とした編集用イラストであり、PixVerse の出力でもなければリップシンク精度の証拠でもありません。これらは、ソースクリップを選択する際に、顔が明瞭で口が遮られていないことがなぜ重要であるかを示すためのものです。

オリジナルの編集用静止画であり、PixVerse の出力ではありません。正面かつ安定した顔は、発話のタイミング合わせを確認するための実用的な最初の入力です。

最初のテストは控えめにしましょう：1 人の可視化可能なスピーカー、短い文、クリアな発話、カメラの動きが少ないものをお勧めします。「Speech ナラティブガイド」と「メディアアップロードリファレンス」では、現時点においてリップシンクアップロードに関する機能制限が異なる記述があります。そのため、コピーしたサイズや再生時間は恒久的な普遍的ルールとは見なさないでください。現在のエンドポイント固有のドキュメントを確認し、最初のサンプルは十分に短く保ってください。PixVerse の API クレジットは Web アプリの会員資格とは別管理です。バッチ処理を開始する前に残高を確認してください。

ID を混同しないよう、外部メディアをアップロードしましょう

すでに PixVerse が生成した video_id をお持ちの場合は、動画のアップロードはスキップしてください。それ以外の場合は、POST /openapi/v2/media/upload を通じてサポート対象の外部動画をアップロードし、返された Resp.media_id を video_media_id として保存します。録音済みの音声トラックも、同一のメディアエンドポイントでアップロードし、返された Resp.media_id を audio_media_id として保存します。PixVerse では、MP4、MOV、WebM などの一般的な動画形式および MP3、WAV、M4A、AAC などの音声形式がドキュメント化されています。転送前に、現在のフォーマットおよび機能制限を必ず確認してください。

成果物は用途ごとに名前を付けましょう：speaker-base-v1.mp4、line-01-clean-v1.wav、およびそれらのメディア ID を含むジョブ記録です。音声の開始時に顔が明確に映っていることを確認し、不要な無音部分をカットし、ソースクリップが新しいセリフに対して十分な口の動きを提供しているかを検証してください。

オリジナルの編集用静止画。斜め 3/4 の構図はレビュアーに奥行きの手がかりをより多く与えますが、タイミングのずれが生じた場合、歯・顎・唇の輪郭を隠すのが難しくなります。

TTS を使用する場合は、完成済み音声のアップロードはスキップしてください。音声リストを照会し、組み込みスピーカー ID を選択するか、許諾を得た上で別途アップロードしたサンプルからカスタム音声を作成してください。auto がすべての言語に対応していると想定しないでください。実際に選択したスピーカー ID を記録してください。複数のスピーカーを扱う場合は、それぞれ別個のクリップを作成し、後で統合してください。

native-audio 動画ガイドでは、音声・環境音・動きが共同でレビューされるべき理由が説明されています。実在する人物の顔または音声を利用する際には、事前に同意を得てください。また、合成音声を用いる場合には、適切な場所でその旨を明記してください。

1 つの有効な生成リクエストを送信しましょう

公式の生成エンドポイントは https://app-api.pixverse.ai/openapi/v2/video/lip_sync/generate です。PixVerse では、各新しい API リクエストに対して API-KEY と新しい Ai-trace-id の指定が必須です。API キーはサーバーサイドで安全に保管し、ブラウザの JavaScript コードや記事内のサンプルには記載しないでください。トレース ID を再利用すると、意図した新規タスクの開始ではなく、以前の結果が返される可能性があるため、各トレース ID について入力 ID、スクリプトバージョン、応答をログに記録してください。このプレースホルダー要求では、PixVerse によって生成されたソース動画とアップロード済みの最終音声が使用されます。例として示された数値を、ご自身のアカウントから返される ID に置き換えてください。本記事では実行されていません。

curl -X POST 'https://app-api.pixverse.ai/openapi/v2/video/lip_sync/generate' \
  -H "API-KEY: $PIXVERSE_API_KEY" \
  -H "Ai-trace-id: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"source_video_id":123456,"audio_media_id":234567}'

外部動画を使用する場合は、source_video_id を video_media_id に置き換えます。テキスト・トゥ・スピーチ（TTS）を使用する場合は、audio_media_id を lip_sync_tts_speaker_id および lip_sync_tts_content の両方に置き換えます。これらは併用ではなく、代替パスです。レスポンスのラッパーには ErrCode、ErrMsg、Resp が使用されます。タスク作成が成功した場合、Resp.video_id が保存すべき識別子です。これは再生可能なファイルの生成完了を保証するものではありません。

呼び出し前に、動画 ID の種類と音声モードのいずれか一方を検証してください。空の TTS スクリプトは拒否します。価格をハードコードせず、返されたクレジットを記録します。各ラインおよびタスクのレスポンスを、視覚的連続性を確保するための最初と最後のフレームによる引継ぎのような安定したショット ID に関連付けます。

ジョブの状態をポーリングし、結果を追跡可能に保つ

タスク作成後は、返された video_id を用いて GET /openapi/v2/video/result/{id} を実行します。PixVerse では、ステータス 5 を「生成中」、ステータス 1 を「成功」と定義しています。HTTP 応答が成功した場合や、作成呼び出しで ErrCode: 0 が返された場合でも、それはタスクが受理されたことを意味するだけであり、生成された動画が審査を通過したことを保証するものではありません。ステータスが 1 になった時点で、レスポンスから出力 URL を取得し、URL の有効期限切れやアクセスルールの変更前に、通常のアセット方針に基づいてコピーを保存してください。

ステータス 7 は「コンテンツモデレーション失敗」、ステータス 8 は「生成失敗」と文書化されています。これらはそれぞれジョブの停止を意味し、無限にポーリングしてはなりません。本番環境のポーラーは、待ち時間を制限し、バックオフを実装し、最後に観測されたステータスを永続的に記録する必要があります。ワーカーが再起動した場合、同じ課金タスクを再度作成するのではなく、保存済みの video_id から再開してください。意図的に新しいリクエストを行う場合は新しいトレース ID を使用しますが、処理が遅いだけのタスクに対してはリトライを発生させないでください。

オリジナルの編集用静止画。広角ショットは、パフォーマーが動きながらも顔のタイミングが読み取れるかどうかをテストしますが、静止画では実際の口唇同期は確認できません。

ショット ID、動画および音声 ID、トレース ID、生成された video_id、最終 URL、審査の判定結果を読みやすい形で記録してください。審査ログには決して認証情報（クレデンシャル）を保存しないでください。PixVerse Agent ワークフロー ガイドでは、全体的な「依頼→ショット」タスクについて説明しています。

口の動き、音声、カット境界をレビューする

最終動画を通常速度で音声付きで再生し、その後、選択した音節周辺を低速再生して確認します。p、b、m のような両唇音と、長い開口母音を含む文を選んでください。これらの子音の直前に口が閉じていること、母音で自然に開いていること、そして話し始めと終わりに目立った遅延がないことを確認します。これは編集者による検査手法であり、公表されたベンチマークや測定された PixVerse 成功率の主張ではありません。

出力とソースを比較します：視線、人物同一性、顎、照明、歯の位置は急激に変化してはなりません。クローズアップとフルクリップの両方を確認してください。これらの静止画は PixVerse の「前／後」比較結果ではありません。

オリジナルの編集用静止画。横顔角度は、正面サムネイルでは隠れがちな顎および口唇の輪郭誤差を明らかにします。

以下に再生可能なクリップを示します。これは既存の実際の動画 Seedance 対話の例です。PixVerse API や図解中のプレゼンターとは独立しており、フルモーションでの口と声の検査を具体化するためにのみ掲載されています。これは PixVerse が生成した口唇同期結果や性能比較を示すものではありません。

フルモーションでの口と声のレビュー用、独立した Seedance 対話サンプル

全セリフを再生し、口の動き、声、頭部の動き、カットの統合を総合的に評価してください。これは PixVerse の出力ではありません。

シンプルな承認カードを使用します：セリフが聞き取りやすく、意図した拍で開始し、話者の同一性を維持し、通常速度での視聴に耐えられる場合は「合格」、編集境界や音声トリミングのみが不適切な場合は「修正」、口の形・顔・タイミングが全体的に不適切な場合は「不合格」。承認判断はポスターよりも動画ファイルに基づくべきです。別の口唇同期ワークフローの例で一般的なレビュー習慣を比較できますが、そのベンダー固有の制御項目は PixVerse API のフィールドと互換性がありません。

適切なレイヤーでトラブルシューティングを行い、納品を整理する

API がリクエストを拒否した場合、レスポンスとパラメーターのペアを確認してください。動画 ID の種類が入れ替わっている、音声のサンプル ID を最終音声として使用している、TTS フィールドが不足している、またはトレース ID が再利用されているなどの可能性をチェックします。認証、クレジット、メディアタイプ、制限、同時実行数を確認してください。サポートへのスクリーンショットに API キーを貼り付けることは絶対に避けてください。ジョブが成功したものの出力結果が不適切な場合は、エンドポイントを変更しても、元となる幾何学的データ（ソースジオメトリ）の品質向上にはほとんど寄与しません。代わりに、より安定した映像クリップ、明瞭な音声、被写体の遮蔽（オクルージョン）の少ない状況、短い発話、およびフレーム内に顔が一定期間収まっている映像を試してください。タイミングのズレが最初の単語のみで発生する場合は、音声のリードイン（先行部分）と動画の開始フレームを確認してください。また、カット位置でのみズレが発生する場合は、編集境界とルームトーン（無音部）を調整してください。再実行時には弱い1行のみを処理し、承認済みの最良のテイクはそのまま保持します。

Seedance Agent はAPI結果が存在した後に適用されます：承認済みのベースクリップ、音声バージョン、生成された出力、承認ノート、およびアセンブリ判断を一括して保持します。全体の作品を再構築することなく、単一ショットの計画または置き換えが可能です。Seedance Agent は参照資料の整理およびレビューの調整を支援できますが、未テストの PixVerse API呼び出しを実行したり、未検証の PixVerse 結果を保証したりすることはありません。異なるプロバイダーから得られた出力を統合する際は、明確な由来（プロヴェナンス）を維持してください。

結論

信頼性の高い PixVerse リップシンクAPIワークフローでは、1つの動画IDタイプと1つの音声モードを固定し、必要なメディアのみをアップロードします。新規のトレースIDを含む、1つの適切に構成されたリクエストを送信し、返された video_id の処理完了を待って、実際に再生される動画結果を評価します。制限事項および課金に関する公式情報源として、最新の PixVerse ドキュメントを常に参照してください。また、編集上の承認判断はタスク作成とは明確に分離して管理してください。複数の承認済みラインを1つの整合性のある納品物へと統合する必要がある場合、参照資料・レビュー・最終アセンブリを Seedance Agent 内で整理してください。