heygen-digital-avatar

HeyGen デジタルヒューマンによるナレーション

動画のアバターレイヤーを作成します。制作全体、字幕、QC、アーカイブは ra-video-production-director に任せ、このスキルでは HeyGen の認証、アバターの選択、生成、承認済みアバターレイアウトを担当します。

HeyGen の motion_prompt を作成または承認する前に、必ず heygen-avatar-motion を読み込んで適用してください。ユーザーが別の動作を明示的に求めた場合を除き、その動作クラスと検証ゲートは必須です。検証ゲートに不合格の間は、有料生成を決して実行しないでください。

固定プロファイル

作成を始める前に references/pluviobyte-profile.json を読み込んでください。これを機械可読なデフォルトとして扱ってください。同じアバターグループから別のルックに置き換えないでください。

• HeyGen CLI OAuth と Creator サブスクリプションのクレジットで認証してください。シェル変数によって課金経路が意図せず切り替わらないよう、子プロセスの環境変数から HEYGEN_API_KEY を削除して HeyGen コマンドを実行してください。
• references/pluviobyte-profile.json で指定された、ランドスケープの Digital Twin のルックを使用してください。 デジタルヒューマンが指定されていない場合は、Avatar III を使用してください。正確な名称が 数字人5 のプリセットは常に Avatar V を意味し、明示的なプレミアムエンジンのリクエストとして扱います。これを Avatar III として解決しないでください。同じアバターグループの旧式のポートレートルックや、生成されたスーツ／シーンのルックに、黙って置き換えないでください。
• ローカルの tts-skill を使って IndexTTS2 を使用し、音声には pluvio-indextts2-calm-v1 を指定してください。HeyGen に音声を合成させないでください。また、ローカル制作では MiniMax や他の代替手段を使わないでください。
• ナレーションの承認を、有料生成の必須条件として扱ってください。まず IndexTTS2 で音声の全編オーディションを生成し、その正確な音声ファイルをユーザーに渡して、HeyGen に音声をアップロードする前に、そのバージョンへの明示的な承認を待ってください。ユーザーが音声の承認に触れずにデジタルヒューマンを求めた場合は、音声承認が必要だと伝え、オーディションの段階で止めてください。音声を少しでも編集した場合、以前の承認は無効になります。
• デフォルトでは、承認済みの headroom_08 の円形アバターを左下に配置してください。全画面／メインキャンバスのアバターを使うのは、ユーザーが 全屏数字人 または同等に明確な指示を明示的に指定した場合のみです。
• プロファイルにあるコンパクトで落ち着いた円形デザインを使用してください。人物部分は 240px とし、無地の白い枠線を 1 本だけ付け、色付きのアクセントリングは付けないでください。キャンバスのアスペクト比を変更しても、下端の位置を安定させてください。ユーザーから拡大または強調の明示的な依頼がない限り、以前の 300px の人物画像や濃い赤色の外周リングに戻さないでください。
• 生成されたすべてのマスターに、固定のクロップをそのまま適用しないでください。標準コンポジターでは 5 フレームをサンプリングし、macOS Vision で顔の中心を測定したうえで、プロファイルにある人手で確認済みの視覚的オフセットを適用してください。承認済みの黒い T シャツの円形アバターでは、候補 06 によりポートレートは数学的な顔の中心より 20px 下に配置され、横方向のオフセットは 0px に保たれます。完成した円形画像を再測定し、顔の中心の平均がこのオフセット目標の 2px 以内に収まることを必須としてください。プロファイルのクロップはレビュー済みの代替案であり、新しいマスターの中央揃えが確認済みであることの証拠にはなりません。
• 字幕や重要なコンテンツは、アバターの除外ゾーンの外に配置してください。
• Avatar IV/V を使用できるのは、ユーザーが高品質を求めた場合、名称付きプリセット 数字人5 を指定した場合、または Avatar III がレビューに不合格となった場合のみです。生成前に、クレジット／コストの増加見込みを伝えてください。数字人5 はそれ自体が Avatar V の明示的な指示であるため、コストを伝えた後にエンジンを再確認しないでください。

ワークフロー

1. env -u HEYGEN_API_KEY heygen auth status を実行します。認証情報の種類が oauth、課金タイプが subscription、プランが creator であることを必須とします。 いずれかの条件が異なる場合は、有料の生成を行う前に停止します。

2. tts-skill でナレーション全体の試聴版を生成します。正規の WAV と、 used_fallback=false および minimax_used=false を含む voice_manifest.json が 必須です。試聴版を提示する前に、多言語の名前や専門用語を確認します。

3. 試聴用の WAV（必要に応じてポータブルな MP3 も）をそのままユーザーに渡し、 「音频确认，可以生成数字人」のような明示的な確認を待ちます。承認された WAV の SHA-256 を media/audio-approval.json に記録します。この記録が作成される前に、 音声をアップロードしたり、HeyGen リクエストを作成したり、クレジットを消費したり しないでください。

4. アップロードの直前に WAV の SHA-256 を再計算します。承認済みのハッシュと異なる 場合は承認を無効にし、ユーザーに伝えて手順 3 に戻ります。「続けて」「そのまま 作って」「アバターを作って」といった依頼は、ユーザーが試聴版そのものを明示的に 承認しない限り、音声の承認にはなりません。

5. 承認済みの固定音声から ra-audio-to-subtitles で本番用字幕を生成します。最終 合成の前に caption-qc.json の検査に合格することを必須とします。

6. 承認済みの固定 WAV を env -u HEYGEN_API_KEY heygen asset create --file <narration.wav> でアップロードし、JSON 応答をプロジェクトに保存します。認証情報をファイルや ログにコピーせず、アセット ID を抽出します。

7. heygen-avatar-motion を使って各意味セクションを分類し、実行に使う正確な モーションプロンプトを保存して、その検証ゲートに合格させます。説明を行う本文 セクションでは、手を画像の外に完全に出す設定をデフォルトとし、手の動きは意味の ある結果や結論の領域に限ります。

8. リクエストを作成する前に、指定されたプリセットからエンジンを決定します。デジタル ヒューマンの指定がない場合は、fit=contain と engine.type=avatar_iii を指定して、 16:9、1080p のアバターマスターを 1 つ生成します。数字人5 の場合は、同じく マスターを 1 つだけ生成し、engine.type=avatar_v を指定して、プレミアムエンジンの ガードを通します。

   python3 scripts/build_request.py \
     --audio-asset-id '<asset-id>' \
     --title '<project title>' \
     --engine avatar_v \
     --allow-premium-engine \
     --output media/heygen-create-request.json
   env -u HEYGEN_API_KEY heygen video create \
     -d media/heygen-create-request.json --wait \
     > media/heygen-create-response.json
   

9. 完成したマスターを heygen video download でダウンロードします。要求された すべてのアスペクト比で、このマスター 1 つを再利用します。クロップ、円形表示の 配置、背景、キャンバスの比率を変更するだけのために、2 回目の生成にクレジットを 消費しないでください。

10. デフォルトのレイアウトでは、マスターを scripts/compose_circle_avatar.py で重ね ます。デフォルトの --center-mode auto は現在のマスターをサンプリングし、測定 したクロップとレビュー済みの視覚オフセットを適用してから、レンダリングされた 円形表示がそのターゲットと一致することを検証します。生成されたセンタリング レポートをアーカイブします。Remotion/HyperFrames で実装する場合は、フォール バックの座標をそのままコピーせず、同じ測定、視覚オフセット、2px のゲートを 再現する必要があります。

11. フルスクリーンモードが明示されている場合は、HeyGen マスターをメインビジュアルに 使用し、円形合成ツールをスキップします。本番用ノートに layout=fullscreen_explicit を記録します。

12. メディアストリーム、長さ、代表的なフレーム、字幕のクリアランス、髪の映り切り、 ヘッドルームの削減、音声の出所、字幕の QC を確認します。その後、最終的な アーカイブ納品について ra-video-production-director に従います。

標準コンポジター

ベース編集がすでに要求された出力サイズになっている場合に使用します。

python3 scripts/compose_circle_avatar.py \
  --base <base-video.mp4> \
  --avatar <heygen-master.mp4> \
  --output <final.mp4> \
  --layout auto \
  --audio-source avatar \
  --centering-report <centering-report.json>

auto は、承認済みの 1920x1080 および 1080x1920 のレイアウトに対応します。ナレー ションのみの合成では、アバターの音声を正とします。固定ナレーションがすでにベース 編集に含まれている場合に限り、--audio-source base を使用します。ナレーションを 2 つ重ねないでください。

新たに生成したマスターには、適応型の顔測定パスが必須です。--center-mode profile は診断に限り、レビュー済みの黒い T 字型のフォールバッククロップを使用します。 それでも、レンダリング後の 2px チェックに合格し、レビュー済みの視覚オフセットの ターゲットと一致する必要があります。--crop-x と --crop-y を併用できるのは、 手動で修正することが明示的にレビュー済みの場合のみです。ローカルのフレーミングを 修正するために再生成したり、HeyGen クレジットを追加で消費したりしないでください。

クレジットのガード

生成の前に、作成する HeyGen マスターの数を明示してください。デフォルトの数は 1 です。レイアウトの実験ではローカルで再構成し、追加の HeyGen クレジットを一切消費しないでください。リトライ時に完了済みの作業を検出して再利用できるよう、リクエスト／レスポンスの JSON とダウンロードしたマスターをプロジェクト内に保存してください。

出力要件

以下の成果物をエンジニアリングプロジェクト内に保持してください。

• media/narration.wav と media/voice_manifest.json
• 明示的に承認された音声の SHA-256 を含む media/audio-approval.json
• media/heygen-asset-response.json
• media/heygen-create-request.json
• media/heygen-create-response.json
• media/pluviobyte-avatar-master.mp4
• 制作用字幕の成果物と caption-qc.json
• 最終 MP4、メディアプローブ、コンタクトシート、SHA-256 の記録
• サンプリングしたフレームの測定値、レビュー済みの視覚オフセット目標、適用したソースクロップ、最終的な平均中心、軸ごとの目標偏差、許容値、および status: pass を含むセンタリングレポート

OAuth トークンや API キーはプロジェクト成果物に保存しないでください。