heygen-translate

HeyGen 動画翻訳

既存の動画を175以上の言語に翻訳して吹き替えます。プレゼンターの声をターゲット言語でクローンし、新しい音声に合わせて唇の動きを再同期して、完全に吹き替えられた動画を返します。元の動画とターゲット言語を指定すると、エンジンが文字起こし、翻訳、音声クローン、リップシンク、（オプションで）映像に焼き込む字幕を処理します。

これは新しい動画を生成する機能ではありません。元の動画のプレゼンター、パフォーマンス、構図、ブランドアセットはそのまま維持されます。既存の映像に翻訳を重ねます。

ユーザー向けの動作

1. 簡潔にします。 チャットに翻訳ID、生のAPIペイロード、ステータスJSONをそのまま表示しないでください。内部処理ではなく、結果（動画リンク、言語）を伝えてください。
2. 内部用語は使いません。 「ポーリング」、「video_translation_id」、「asset_id」、「v3エンドポイント」と言わず、「翻訳中です」、「もうすぐ完了です」、「ファイル」と伝えてください。
3. ポーリング中は何も伝えません。 時間のかかる翻訳をバックグラウンドで実行し、（a）結果を届けるとき、（b）5分を超えて停滞したとき（1回だけ更新を伝える）、（c）致命的なエラーが発生したときにのみ応答してください。
4. 結果の連絡は1回にまとめます。 動画が完成したら、リンクと1行の要約（ターゲット言語、再生時間、モード）を送信してください。APIの各フィールドをすべて伝える必要はありません。
5. 通信方式について説明しません。 MCP、CLI、OpenClawプラグインのどれを使うかは内部処理です。セッション開始時に黙って選択し、使用している方式については決して言及しないでください。
6. ユーザーの言語で応答します。 最初のメッセージから言語を判定してください。返信、確認、質問はその言語で行います。技術的なCLI/APIの指示は英語のままにしてください。

APIモードの判定

セッション開始時に通信方式を1つ選択してください。混在させず、途中で切り替えず、選択について説明しないでください。

次の順序で判定してください。

1. OpenClawプラグインモード — OpenClaw内で実行されており、video_generate ツールがHeyGenの翻訳モデルを公開している場合は、それを優先してください。現在、このプラグインは動画を生成できますが、翻訳機能を直接公開していません。HeyGenが video_generate を通じた翻訳を提供するまでは、次の選択肢に進んでください。
2. CLIモード（APIキーによる上書き） — 環境に HEYGEN_API_KEY が設定されており、かつ heygen --version の終了コードが0の場合は、CLIを使用してください。APIキーが設定されていることは、ユーザーがAPIへの直接アクセスを希望している明示的な合図です。
3. MCPモード — HEYGEN_API_KEY が設定されておらず、HeyGen MCPツール（mcp__heygen__*）が利用可能な場合です。OAuth認証を使用し、ユーザーのプランのクレジットを利用して実行します。
4. CLIモード（フォールバック） — MCPツールが利用できず、heygen --version の終了コードが0の場合です。heygen auth login で認証してください。
5. どちらも利用できない場合 — ユーザーに一度だけ、次のように伝えてください。「このスキルを使用するには、HeyGen MCPサーバーに接続するか、HeyGen CLIをインストールしてください。curl -fsSL https://static.heygen.ai/cli/install.sh | bash を実行し、その後 heygen auth login を実行してください。」

認証の確認（API を呼び出す前に実行）

モードを検出した後、フェーズ 1 に進む前に認証が実際に機能することを確認します。これにより、入力を集めてから送信時に認証エラーが発生し、ユーザーの時間を無駄にすることを防ぎます。

• MCP モード： 認証は OAuth で処理されるため、確認は不要です。
• CLI モード： heygen auth status を実行します（出力は表示しません）。終了コードが 0 の場合は続行します。0 以外の場合（キーなし、期限切れ、無効）：
  1. ユーザーに尋ねます：「続行するには HeyGen API キーが必要です。https://app.heygen.com/settings?nav=API から取得して、ここに貼り付けてください。」
  2. キーを受け取ったら、保存します：echo "<key>" | heygen auth login（~/.heygen/credentials に書き込み、セッションをまたいで保持されます）。
  3. 確認します：heygen auth status。それでも失敗する場合は、エラーを提示して停止します。

これは初回のみの設定です。heygen auth login でキーを保存すると、今後のセッションでは自動的に使用されます。heygen auth status が成功した場合は、再度尋ねないでください。

厳守事項：

• curl api.heygen.com/... は絶対に呼び出さないでください。 このスキルの各操作には CLI コマンドがあり、対応している場合は MCP ツールもあります。それらを使用してください。
• MCP モードでは mcp__heygen__* ツールのみを使用してください。 翻訳がまだ MCP で提供されていない場合は、翻訳操作に限り CLI に切り替えてください。生の HTTP 呼び出しを組み立てないでください。
• CLI モードでは heygen ... コマンドのみを使用してください。 引数を確認するには heygen video-translate --help と heygen video-translate <subcommand> --help を実行してください。作成コマンドの完全な JSON 形式を確認するには --request-schema を使用してください。
• 以下の操作は MCP と CLI を並べて示しています。検出されたモードの列のみを参照してください。

MCP ツール名（MCP モードのみ）

create_video_translation（単一言語）。複数言語と校正はまだ MCP で提供されていないため、該当する場合は CLI に切り替えてください。利用可能なツールを確認するため、セッション開始時に mcp__heygen__* ツールの一覧を取得してください。ツールの提供状況は変化します。

CLI コマンドグループ（CLI モードのみ）

heygen video-translate
├── languages list              # supported target languages
├── create                      # submit a translation job (single or batch)
├── get <id>                    # check status / fetch result
├── list                        # list past translations
├── update                      # update job metadata
├── delete                      # delete a job
└── proofreads
    ├── create                  # extract editable subtitles before final render
    ├── get <id>                # check proofread session status
    ├── srt get <id>            # download the extracted SRT
    ├── srt update <id>         # upload edited SRT
    └── generate <id>           # render the final video from approved SRT
heygen asset create --file <path>   # for local source video uploads (max 32 MB)

すべてのコマンドで --help を使用できます。作成コマンドの完全な JSON 本文を確認するには、--request-schema を使用してください。CLI の出力は、標準出力に JSON、標準エラー出力に {error:{code,message,hint}} 形式のエンベロープが表示されます。終了コードは 0 が成功、1 が API エラー、2 が使用方法のエラー、3 が認証エラー、4 がタイムアウトです。ジョブが完了するまで待機するには、create に --wait を追加してください（デフォルトのタイムアウトは 20m です）。

📖 CLI/MCP のエラーから対応方法への詳細なマッピング → references/troubleshooting.md

---

デフォルトのワークフロー

このスキルは 4 つのフェーズで実行されます。質問するのはフェーズ 1（情報収集）のみです。フェーズ 2（事前確認）は無言で実行します。フェーズ 3（送信とポーリング）も無言で実行します。フェーズ 4（納品）では短いメッセージを 1 つ送ります。

Phase 1 — Discovery       — gather minimum needed inputs from the user
Phase 2 — Pre-flight      — validate language, classify content, set flags
Phase 3 — Submit + Poll   — kick off, background poll, surface only on done/fail
Phase 4 — Deliver         — post the result with one-line summary

フェーズ 1 — 情報収集

すでに把握していることは尋ねず、不足していることだけを質問します。ユーザーの言語でやり取りしてください。フォームは絶対に使用しないでください。 1 回のターンにつき、質問は最大 1～2 個です。

必須の入力（揃うまで先に進まないでください）：

1. ソース動画。 公開 URL、ローカルファイルのパス、または前のステップで取得した HeyGen の asset_id。ユーザーから提示されていない場合は、次のように尋ねてください。「ソース動画は何ですか？URL、ファイルのパス、または既存の HeyGen アセットを指定してください。」
2. 翻訳先の言語。 ユーザーの言語で自由回答形式の質問をしてください。「何語に翻訳すればよいですか？」 選択肢を提示したり、言語をあらかじめ割り当てたりしないでください。ユーザーが自由に入力できるようにします。1 つの言語でも、複数の言語でも、地域に特化したバリエーションでもかまいません。指定された内容を受け入れ、フェーズ 2 の標準言語リストと照合してください。

重要な入力（指定されていない場合は、適切なデフォルトを使って尋ねてください）：

3. 話者の人数。 デフォルトは 1 人で、ほとんどのユーザーはこれに該当します。曖昧な場合は 1 度尋ねてください。「動画には何人の話者が登場しますか？」 話者数の間違いは、品質を損なう最大の原因です。話者を誤認すると、翻訳の途中で声が入れ替わります。複数人が登場するコンテンツでは、この確認を省略しないでください。
4. コンテンツの種類。 通常は尋ねる必要はありません。動画から推測して確認してください。以下の 5 つのプロファイルで、約 95％のケースをカバーできます。本当に判断が難しい場合に限り、尋ねてください。
5. 字幕の設定。 トークヘッドと企業向けコンテンツではデフォルトでオン、ポッドキャストや音声のみのコンテンツではデフォルトでオフです。デフォルトを変更する場合は、フェーズ 4 で簡潔に伝えてください。
6. 動画の長さの許容範囲。 次のように尋ねてください。「翻訳後の動画は元の動画とまったく同じ長さにする必要がありますか。それとも、少し長くなったり短くなったりしてもかまいませんか？長さに余裕を持たせると、翻訳した音声を無理に早口にしたり圧縮したりせず、快適な速度で話せるようになるため、通常はより自然な仕上がりになります。」 デフォルトの推奨設定は、長さに余裕を持たせることです（enable_dynamic_duration: true）。タイムライン、広告枠、外部音声トラックとの同期など、フレーム単位で正確なタイミングが必要な場合に限り、false に設定してください。

任意（関連する場合に限り尋ねてください）：

7. 用語集／翻訳しない用語。 企業向けまたは技術的なコンテンツでは、次のように尋ねてください。「原文のままにしておくべき製品名、会社名、専門用語はありますか？」 HeyGen は現在、固定の用語集を受け付けていないため、重要性が高い場合は、校正ステップ（フェーズ 3-校正）で参考情報として使用します。
8. 一部の翻訳。 ユーザーが特定の区間（「イントロだけ」「1:30 から 4:00 まで」など）を指定した場合は、start_time と end_time を秒単位で記録します。
9. 最終レンダリング前の校正。 デフォルトではオフです（処理が速く、承認の回数も少なくなります）。次の場合はデフォルトでオンにします。長い動画（3 分超）、企業向け／ブランドコンテンツ、法務／医療／教育など重要性の高いコンテンツ、ユーザーが母語として読み、内容を確認できる言語。次のように尋ねてください。「最終レンダリングの前に、字幕を確認して編集しますか？約 5 分かかりますが、誤った用語を修正できます。」

📖 言語ペアで注意すべき点（敬語のレジスター、RTL 言語、声調による圧縮、リップシンクの限界）→ references/language-locale-guide.md

フェーズ 2 — 事前確認

無言で行います。ユーザー向けの余計な説明はしません。次の 3 つの確認を順番に行います。

確認 2a：言語の検証。

MCP： list_video_translation_languages()（公開されている場合）。それ以外の場合は CLI を使用します。 CLI： heygen video-translate languages list | jq -r '.data.languages[]'

このリストには正確な文字列（"Spanish (Spain)"、"Chinese (Mandarin, Simplified)"、"Arabic (Saudi Arabia)"）が含まれています。ユーザーの入力を大文字と小文字を区別せずに照合し、これらの文字列と一致させます。「Spanish」と指定された場合は、既定で「Spanish (Spain)」を選択し、フェーズ 4 で確認します。「Chinese」と指定された場合は、既定で「Chinese (Mandarin, Simplified)」を選択します。地域が指定された場合（「Mexican Spanish」など）は、該当する言語（「Spanish (Mexico)」など）に対応付けます。一致するものがない場合は、最も近い候補から選ぶようユーザーに尋ねます。

確認 2b：ソース動画のルーティング。

ユーザーから提供されたソース	ルーティング
公開 HTTPS URL（認証不要で、HEAD に対して動画 MIME タイプを返す）	{type: "url", url: "..."} としてそのまま渡します
認証が必要な URL、403、404、または HTML の応答	ユーザーに伝え、公開 URL またはローカルファイルを求めます
ローカルファイルパス	heygen asset create --file <path>（CLI）または upload_asset（MCP）でアップロードします。最大 32 MB です。返された asset_id を {type: "asset_id", asset_id: "..."} として使用します
既存の HeyGen asset_id	{type: "asset_id", asset_id: "..."} としてそのまま渡します

📖 アセットのルーティングに関する例外（非常に大きなファイル、署名付き URL、認証が必要なソース）→ references/asset-routing.md

確認 2c：コンテンツプロファイル。

ソースに基づいて、次のプロファイルから 1 つ選びます。5 つすべてをユーザーに提示しないでください。ソースが本当に曖昧な場合（例：音楽が多いトーキングヘッド動画で、音声強調が役立つか判断できない場合）にのみ尋ねます。

プロファイル	使用する状況	フラグ
トーキングヘッド／プレゼンター（既定）	1 人がカメラに向かって話す、音声が明瞭な場合	mode: precision、enable_speech_enhancement: true、enable_caption: true、enable_dynamic_duration: true、keep_the_same_format: true
ポッドキャスト／音声のみ	映像が静止している、重要でない、または存在しない場合	mode: precision、translate_audio_only: true、enable_speech_enhancement: true、enable_caption: true
音楽／サウンドトラックが多い動画	BGM が音声の邪魔をする場合	mode: precision、disable_music_track: true、enable_speech_enhancement: true、enable_dynamic_duration: true、keep_the_same_format: true
複数話者	区別できる話者が 2 人以上いる場合	トーキングヘッドの既定値に加えて speaker_num: <count> を指定します。この場合、話者数は必須です。推測しないでください。
企業／ブランド向け	ブランドボイス、用語集の厳守、重要度の高い用途	トーキングヘッドの既定値に加えて、ユーザーが持っている場合は brand_voice_id を指定します。このプロファイルでは、校正を強く検討してください。

常に適用する設定：

• ユーザーが明示的に「fast」／「quick」／「speed」を求めない限り、mode: "precision" を指定します。
• enable_dynamic_duration：フェーズ 1 でユーザーが回答した、再生時間の柔軟性に関する質問に基づいて設定します。既定値は true（推奨）です。これにより、翻訳音声をソースの正確なタイミングに無理に詰め込まず、自然な長さで再生できます。固定長の出力が必要だとユーザーが明示した場合に限り、false に設定します。音調の圧縮を考慮すると、en→zh、en→ja、en→ko（アジア言語では短くなる傾向があります）、de→en、ja→en（長くなる傾向があります）、ar/he/ur（RTL とレジスターの変化）では、特に柔軟性が重要です。
• 映像を含む翻訳では、ソースの解像度とビットレートを維持し、吹き替え動画のエンコードを原本に合わせるため、keep_the_same_format: true を指定します。
• enable_watermark: false を指定します（既定値です）。

フェーズ 3 — 送信とポーリング

無言で行います。バックグラウンドで処理します。ユーザーに進捗を伝えるのは、（a）言語ごとの完了時、（b）言語ごとの致命的なエラー発生時、（c）5 分を超える進捗確認時に限ります。

分岐：

• 標準パス（校正 = OFF）：翻訳を送信し、バックグラウンドでポーリングして、結果を渡します。
• 校正パス（校正 = ON）：校正セッションを作成 → SRT をダウンロード → ユーザーが編集するか、こちらで編集を支援 → 編集済み SRT をアップロード → 最終版を生成 → バックグラウンドでポーリング → 結果を渡します。

標準パス

バッチ構文を使用して、ターゲット言語ごとに 1 つのジョブを送信します（--output-languages は複数を受け付けます）。

MCP (執筆時点では一度に 1 言語のみ):

create_video_translation(
  video={type, url|asset_id},
  output_languages=["Spanish (Spain)"],
  mode="precision",
  enable_speech_enhancement=true,
  enable_caption=true,
  enable_dynamic_duration=true,
  keep_the_same_format=true,
  speaker_num=<n>,           # only when known multi-speaker
)

CLI:

heygen video-translate create \
  -d '{"video":{"type":"url","url":"https://..."},"output_languages":["Spanish (Spain)","Japanese (Japan)"]}' \
  --mode precision \
  --enable-speech-enhancement \
  --enable-caption \
  --enable-dynamic-duration \
  --keep-the-same-format \
  --speaker-num 1 \
  --title "<short title>"

レスポンスは言語ごとに 1 つの video_translation_id を返します。それらをすべて記録してください。

ポーリング（サイレント、バックグラウンド）:

1 言語のみを実行する場合は、create で --wait を使用して完了までブロックします。バッチの場合は --wait を外し、各 ID をポーリングします:

# CLI mode polling (background)
heygen video-translate get <video-translation-id>
# Returns { data: { status: "pending"|"running"|"completed"|"failed", video_url, ... } }

ポーリングの間隔: 最初の 3 分間は 30 秒、その後は 60 秒。ほとんどの翻訳は 5～15 分で完了しますが、一部（長い動画、バッチ処理された言語）は 30 分以上かかります。ハードタイムアウト: 翻訳ごとに 60 分 — それを超えた場合はスタックとみなし、問題を表面化させます。

MCP での同等機能: get_video_translation(id)（公開されている場合）。それ以外の場合は CLI にフォールバックしてポーリングします。

📖 バックグラウンドポーリングのパターン（フォアグラウンドでポーリングしない / ハーネス固有の注意事項） → references/troubleshooting.md#polling

校正パス

重要なコンテンツの場合、エンジンが最終レンダリングを確定する前に、ユーザーが翻訳済み字幕を確認・編集できるよう、先に校正セッションを実行します。

# 1. Create proofread session — returns proofread_ids (one per language)
heygen video-translate proofreads create \
  -d '{"video":{"type":"url","url":"https://..."}}' \
  --output-languages "Spanish (Spain)" \
  --mode precision \
  --enable-speech-enhancement \
  --keep-the-same-format \
  --speaker-num 1 \
  --title "<short fileNAME-safe title>"
# → status: processing  (3–5 min for short videos)

# 2. Poll until completed (or failed + failure_message)
heygen video-translate proofreads get <proofread-id>
# → status: completed

# 3. Fetch presigned URLs for editable + original SRTs
heygen video-translate proofreads srt get <proofread-id> > /tmp/srt-resp.json
SRT_URL=$(jq -r '.data.srt_url'          /tmp/srt-resp.json)  # target-lang, edit this
ORIG_URL=$(jq -r '.data.original_srt_url' /tmp/srt-resp.json) # source-lang transcript
curl -s "$SRT_URL" -o /tmp/proofread.srt

# 4. Edit /tmp/proofread.srt by hand or sed (glossary, register, names)
#    See references/proofreads-workflow.md for the full edit playbook.

# 5. Upload the edited SRT as an asset, then reference it by asset_id.
#    `heygen asset create` accepts srt (png, jpeg, mp4, webm, mp3, wav, pdf, srt).
#    Fallback: host at a public URL and use {"type":"url","url":"..."}.
ASSET_ID=$(heygen asset create --file /tmp/proofread.srt | jq -r '.data.asset_id')
heygen video-translate proofreads srt update <proofread-id> \
  -d "{\"srt\":{\"type\":\"asset_id\",\"asset_id\":\"$ASSET_ID\"}}"

# 6. Kick off final render — returns a video_translation_id
heygen video-translate proofreads generate <proofread-id> --captions
# → {"data":{"video_translation_id":"<vid-id>","status":"processing"}}

# 7. Poll the translation to completion (NOT proofreads get — graduates here)
heygen video-translate get <vid-id>
# → status: running → completed; data.video_url has the final mp4

📖 校正を強く勧めるべき場面、よくある SRT の編集、用語集の規律 → references/proofreads-workflow.md

フェーズ 4 — 納品

完了した言語ごとに 1 つのメッセージ。形式:

✅ スペイン語（スペイン） — <video_url> 1分47秒、precision モード、キャプション オン。

言語が失敗した場合: 原因を添えた短い 1 行（トラブルシューティングリファレンスから）。ユーザーが求めない限り、再試行の選択肢を大量に提示しないでください。ユーザーが多くの言語をバッチ処理した場合は、完了したものから順に納品してください — すべてが完了するのを待ってから投稿しないでください。

ソース品質に関する免責事項。 翻訳はソースを上回ることはできません。ソースの音声がこもっている、カットが速い、顔が大きく隠れている、解像度が低いなどの場合、リップシンクと音声品質は低下します。フェーズ 2 でこれらの条件を検出した場合（またはユーザーが言及した場合）は、事前に警告してください。悪い結果が出た後にこれを表面化させないでください。

フィードバックの報告（CLI モード）

翻訳が納品されたら — または途中で問題に遭遇した場合 — タスクごとに 1 回これを実行します:

heygen feedback --rating <1-5> --comment "<what worked, or what broke and what you tried>"

• --rating: 5 = 非常にうまくいった · 3 = 摩擦はあったが機能した · 1 = 壊れた / 使えない。
• --comment: あらゆるバグ、古いドキュメント、不足しているフラグ、紛らわしい動作、およびそれを引き起こしたコマンドやフロー。

匿名で、API キーは不要で、分析がオプトアウトされている場合（HEYGEN_NO_ANALYTICS または heygen config set analytics false）は何も行いません。これは CLI チームの主要なシグナルチャネルです — 静かに終わる実行は彼らに何も伝えません。CLI モードのみ: MCP または OpenClaw プラグインモードではスキップしてください（これらは MCP/プラグインのサーフェスを経由し、フィードバックコマンドがありません）。

---

組み込みの知見

上記のデフォルトは一般的なケースをカバーしています。以下の判断は、このスキルを汎用の API ラッパーから際立たせるものです。これらは暗唱するチェックリストではなく、ワークフロー中の判断材料として使用してください。

話者数は品質を損なう最大の要因

トーキングヘッドの場合: 話者は 1 人。インタビュー / ポッドキャスト / パネルの場合: 正確に数え、推測しないでください。エンジンは speaker_num で声を分離します。数が間違っていると、吹き替え出力で声が話者間で混ざります。ユーザーが確信を持てない場合は、動画をスクラブして数えるよう依頼してください。

ソース品質のトリアージ（提出前に実施）

フェーズ 2 で 30 秒のトリアージを行うことで、質の低い翻訳を修正するために 10〜30 分かかる事態を防げます。ソースの最初の約 10 秒を視聴して、次の点を確認してください。

• 音声： 話し声は明瞭ですか？ 背景音楽が支配的ですか？ ノイズやヒスノイズはありますか？ → 話し声が不明瞭な場合は、enable_speech_enhancement: true をデフォルトで設定します。音楽が支配的な場合は、disable_music_track: true を設定します。両方に当てはまる場合は、フラグにかかわらず品質が低下する可能性があることをユーザーに伝えてください。
• 顔の見えやすさ： 話者の顔はほとんどの時間、カメラに映っていますか？ 正面を向いていて、十分な明るさがありますか？ → 大きな遮蔽（サングラス、顔に手を当てているなど）、横顔のみの映像、非常に速いカット、または 720p 未満の顔映像では、リップシンクの品質に上限が生じます。
• 画面上のテキスト： ソース言語の字幕が映像に焼き込まれていますか？ → これらは再描画されません。吹き替え後の出力にもソース言語のまま残ります。ユーザーが新しい言語の字幕を希望する場合は、enable_caption: true を提案し、既存の焼き込み字幕についても警告してください。

ロケールの組み合わせに関する注意点

• 音声の圧縮／伸長。 en→zh、en→ja、en→ko では約 30％短くなり、de→en、ja→en では長くなります。en→ar/he では通常、長くなります。動的な長さ設定（フェーズ 1 の尺の柔軟性に関する質問）は、これらの組み合わせで特に重要です。これを設定しないと、en→zh では 30％長すぎるタイムラインに音声を詰め込むことになり、人工的にゆっくり聞こえます。ユーザーが固定尺の出力を選んだ場合、圧縮率が高い組み合わせでは品質が低下することを伝えてください。
• 丁寧さ／文体。 ja-JP（敬語）、ko-KR（敬語）、de-DE（Sie と du）、th-TH（王室向け／丁寧／カジュアル）、id-ID（フォーマル／口語）では、エンジンはデフォルトで中立的なフォーマル表現を選びます。ソースが会話調で、ユーザーがターゲット言語でも同じ文体を希望する場合は、校正時にその点を明示するか、元の表現よりややフォーマルに聞こえる可能性を事前に伝えてください。
• RTL 言語。 アラビア語、ヘブライ語、ウルドゥー語、ペルシア語では、字幕は右から左に表示されます。焼き込み字幕は、ソース動画のローワーサードのグラフィックと、反対側で重なる可能性があります。ソースに画面上のテキストやローワーサードのグラフィックがある場合は、音声のみの翻訳を提案するか、字幕スタイルの確認を含む校正を提案してください。
• 地域による違いが重要です。 スペイン語（スペイン）、スペイン語（メキシコ）、スペイン語（アルゼンチン）では、語彙、イントネーション、話す速度がそれぞれ大きく異なります。ラテンアメリカの視聴者は、カスティーリャ・スペイン語を外国語のように感じることがよくあります。ユーザーが指定した対象地域をデフォルトにしてください。スペイン語で地域が指定されていない場合は、一度確認してください。ポルトガル語（ポルトガル／ブラジル）、フランス語（フランス／カナダ／スイス）、アラビア語（地域ごとに 19 種類）も同様です。
• 中国語（標準中国語）について。 中国本土向けの標準的なデフォルトは「中国語（標準中国語、簡体字）」です。香港や海外の広東語話者のコミュニティ向けには「中国語（広東語、繁体字）」、台湾向けには「中国語（台湾華語、繁体字）」を使用します。これらは相互に置き換えられません。

📖 文体の注意点と既知の特性を含むロケールの組み合わせ一覧 → references/language-locale-guide.md

リップシンクの上限

リップシンクは、次の条件で最も良好になります。

• 安定した正面向きのショット
• 顔の解像度が 720p 以上
• 明るく、鮮明に映った顔
• カットが少ない（長回しのほうが良好）

次の条件では、リップシンクの品質が低下します。

• 横顔、下を向いたショット、顔の一部が隠れている映像
• 速いカット（ショットが 2 秒未満）
• 暗い照明、モーションブラー、低解像度の顔映像
• 顔が素早く動く、大きなジェスチャー

ユーザーのソースにこれらの条件がある場合は、フェーズ 1 または 2 で警告してください。「ご注意ください。ソースには [X] が含まれているため、静止したトーク映像ほどリップシンクが自然になりません。このまま進めますか？ それとも音声のみの翻訳に切り替えますか？」

字幕：焼き込み字幕とサイドカーファイル

enable_caption: true を設定すると、デフォルトで字幕が映像に焼き込まれます。メリット：別ファイルが不要で、どこでも再生できます。デメリット：後から編集できず、ソースのグラフィックと重なる可能性があり、フォントやスタイルも固定されます。字幕のスタイル変更（ブランドキット、言語に適したフォントなど）が必要になる可能性がある重要なコンテンツでは、校正ワークフローを優先してください。サイドカー字幕ファイルとして使える SRT が提供されます。

音声のみの翻訳

translate_audio_only: true を指定すると、リップシンクを完全にスキップします。次のような場合に使用します。

• ポッドキャスト（「動画」が静止画や波形の場合）
• 後で別の動画に合成する音声
• リップシンクが不可能な場合（顔が映っていない、元の映像の顔の品質が非常に低いなど）

出力は音声ファイル（通常は MP3）です。ユーザーには使い方を伝えてください。「翻訳済みの音声トラックが生成されます。編集ソフトで元の動画に合成するか、音声単体でご利用ください。」 音声のみの出力を、リップシンクの品質が低い場合の「回避策」として提案してはいけません。これは別の成果物です。

コストと所要時間への配慮

翻訳料金は元動画の長さに基づきます。5 分の動画を 5 言語に翻訳すると、課金対象は合計 25 分です。ユーザーが一括処理を依頼した場合は、フェーズ 1 で所要時間とコストの見込みを伝えてください。「5 言語 × 5 分なので、翻訳時間は約 25 分です。それぞれのレンダリングには 10～20 分かかります。よろしいですか？」

具体的な金額は提示しないでください（料金は変更される場合があり、プランによって異なります）。元動画の長さと対象言語数に基づく分数と、誠実なレンダリング所要時間の範囲を伝えてください。

エラー原因の読み解き

よくあるエラーレスポンス → 人に分かりやすい原因 → 次の対応：

症状	考えられる原因	対応
400 "video URL not accessible"	URL に認証が必要、HTML が返された、または MIME タイプが誤っている	公開 URL またはローカルファイルを依頼 → アップロード経由で処理
400 "language not supported"	文字列が正規の言語リストと一致しなかった	languages list を再実行し、最も近い候補を提示
"audio extraction" とともにステータスが failed	元動画に聞き取れる音声がない、音声がひどく破損している、またはコーデックが誤っている	元動画に音声があることを確認し、再エンコードを検討
"speaker detection" とともに failed	speaker_num が実際の話者数と一致しない、または音声のノイズが多い	正しい話者数を指定するか、enable_speech_enhancement: true を指定して再送信
running のまま 30 分以上経過	バックエンドのキューまたは一時的な停滞	ステータスを確認し、合計 60 分まで待ってからユーザーに状況を伝える
出力のリップシンクが不自然	元動画の顔の状態（リップシンクの限界を参照）	期待値を調整し、代替案として音声のみの出力を提案
字幕の方向が誤っている	RTL 言語の焼き付け字幕が元のレイアウトと重なっている	校正済み字幕とサイドカー形式の SRT に切り替える

📖 認証とアセットのアップロードエラーを含む、エラーから対応への完全な一覧 → references/troubleshooting.md

---

初回ユーザーの判定

ユーザーが HeyGen の翻訳機能を初めて使うと判断できる兆候：

• 「どの言語に対応していますか？」と尋ねる
• リップシンクと音声のみの違いを知らない
• HeyGen を使ったことがない（アバターがなく、heygen video-translate list に過去の翻訳も表示されない）

初めて利用するユーザーには、動画全体を処理する前に 30～60 秒のテストクリップを提案してください。これにより、長い動画の翻訳を始める前に、元動画の品質、音声クローンの忠実度、リップシンクの限界を確認できます。

元動画の品質に関する免責事項（納品時にそのまま使用）

元動画の品質が境界線上にある場合：

「ご確認ください。元動画には［こもった音声／暗い照明／速いカット／大きな音楽など］が含まれています。翻訳エンジンで元動画の品質を改善することはできないため、吹き替えにも影響が残る可能性があります。このまま進めるか、先に元動画を修正するか、短いクリップで試しますか？」

悪い結果が出た後に伝えてはいけません。フェーズ 2 で伝えてください。

フェーズ 2 ／ ロードマップ（聞かれた場合のみ言及）

現在は proofreads ワークフローで最もよくサポートされていますが、まだ専用のフラグはありません。

• ブランド用語集／翻訳禁止リスト。 SRT 内の自動翻訳された用語を元に戻すことで、proofread 中に適用します。brand_voice_id フラグは翻訳間で音声の一貫性を保つためのもので、用語集用ではありません。
• カスタム SRT 入力。 create の srt フィールド（Enterprise プラン）、またはすべてのプランで proofreads srt update を使ってサポートされています。srt_role: "input" を指定すると、ソース言語にあなたの字幕が適用されます。output を指定すると、対象言語の字幕として適用されます。
• 部分翻訳。 秒単位で start_time ／ end_time を指定します。「2:00〜4:00 の部分だけ翻訳する」といった場合に便利です。
• 複数言語の一括処理。 すでにサポートされています。--output-languages（CLI）または output_languages 配列（MCP）に複数の値を渡してください。言語ごとに 1 つのジョブ ID が返されます。
• Webhook コールバック。 --callback-url と --callback-id を指定すると、ポーリングを完全に省略できます。Webhook エンドポイントがあり、イベント駆動の完了通知が必要な場合に使います。

ベストプラクティス（要点）

1. ユーザーが明示的に速度を求めない限り、常に精度モードを使います。
2. 判断が明らかでない場合は、必ず話者数を確認します。
3. 送信する前に、言語文字列が正式なリストに含まれているか検証します。
4. 新規ユーザーには、短いテストクリップを提案します。
5. ソースの品質が上限を決めます。後からではなく、最初に伝えます。
6. 設定しすぎないようにします。5 つのコンテンツプロファイルで、約 95％ のケースに対応できます。
7. 翻訳には時間がかかります。5〜30 分を目安として伝えます。
8. 文体を合わせます。ソースが会話調で、対象言語が文体の違いを重視する言語（ja、ko、th、de）の場合は、proofread を行います。
9. 長い動画、企業向けコンテンツ、ユーザーが母語として読む言語では、proofread をデフォルトで ON にします。
10. 通信方式について説明しません。MCP か CLI かは内部的なことです。