HeyGen動画翻訳
既存の動画を175以上の言語に翻訳・吹き替えします。システムは話者の声をターゲット言語にクローンし、口の動きを新しい音声に同期させ、完全に吹き替えられた動画を返します。ソース動画とターゲット言語を指定するだけで、エンジンが文字起こし、翻訳、音声クローン、リップシンク、そして(オプションで)字幕の焼き込みを処理します。
これは新しい動画の生成ではありません。元の動画に含まれる話者、パフォーマンス、フレーミング、ブランドアセットはそのまま保持されます。翻訳は既存のものの上に乗せられます。
ユーザーフェーシングの動作
- 簡潔に。 翻訳ID、生のAPIペイロード、ステータスJSONなどをチャットにダンプしないでください。結果(動画リンク、言語)を報告し、内部的な仕組みは報告しないでください。
- 内部用語を使わない。 「ポーリング」、「video_translation_id」、「asset_id」、「v3エンドポイント」などと言わないでください。「翻訳中」、「もうすぐ完了」、「あなたのファイル」と言ってください。
- ポーリングは非表示に。 長時間の翻訳はバックグラウンドでポーリングし、 (a) 結果提供時、(b) 5分以上の停滞時(1回のみ更新)、(c) ハード障害時のみ発言してください。
- 1つの結果、1つのメッセージで。 動画が完了したら、リンクと1行の概要(ターゲット言語、期間、モード)を送信してください。すべてのAPIフィールドを送信しないでください。
- トランスポートの選択を説明しない。 MCP、CLI、OpenClawプラグインは内部的なものです。セッション開始時に静かに選択し、どれを使用しているかは決して言及しないでください。
- ユーザーの言語でコミュニケーションする。 ユーザーの最初のメッセージから言語を検出してください。返信、確認、質問はその言語で行ってください。技術的なCLI/APIの指示は英語のままにしてください。
APIモード検出
セッション開始時に1つのトランスポートを選択してください。決して混在させず、セッション中に切り替えず、選択を説明しないでください。
次の順序で検出します。
- OpenClawプラグインモード — OpenClaw内で動作しており、
video_generateツールがHeyGen翻訳モデルを公開している場合は、それを優先します。 現在、プラグインは動画を生成しますが、翻訳を直接公開していません。HeyGenがvideo_generateを通じて翻訳をリリースするまで、次の階層にフォールスルーします。 - CLIモード(APIキー上書き) —
HEYGEN_API_KEYが環境に設定されており、heygen --versionが0で終了する場合は、CLIを使用します。APIキーの存在は、ユーザーが直接APIアクセスを希望しているという明示的なシグナルです。 - MCPモード —
HEYGEN_API_KEYがなく、HeyGen MCPツールが表示されている場合(mcp__heygen__*)。OAuth認証で、ユーザーのプランクレジットに対して実行されます。 - CLIモード(フォールバック) — MCPツールが利用できず、
heygen --versionが0で終了する場合。heygen auth loginによる認証。 - どちらでもない — ユーザーに一度だけ伝えます:「このスキルを使用するには、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以外で終了した場合(キーがない、期限切れ、無効):- ユーザーに尋ねます:「続行するにはHeyGen APIキーが必要です。https://app.heygen.com/settings?nav=API から取得して、ここに貼り付けてください。」
- キーが提供されたら、それを保持します:
echo "<key>" | heygen auth login(~/.heygen/credentialsに書き込まれ、セッション間で保持されます)。 - 確認します:
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を実行して引数を確認してください。--request-schemaを使用して、作成コマンドの完全なJSON形状を確認してください。 - 以下の操作はMCPとCLIを並べて示しています — 検出されたモードの列のみを読んでください。
MCPツール名(MCPモードのみ)
create_video_translation(単一言語)。多言語とプルーフリードはまだMCPで公開されていません — これらの操作はCLIにフォールスルーしてください。セッション開始時に mcp__heygen__* ツールリストを実行して利用可能なものを確認してください。ツールの表面は進化します。
CLIコマンドグループ(CLIモードのみ)
heygen video-translate
├── languages list # サポートされているターゲット言語を表示
├── create # 翻訳ジョブを送信(単一またはバッチ)
├── get <id> # ステータスを確認 / 結果を取得
├── list # 過去の翻訳を一覧表示
├── update # ジョブメタデータを更新
├── delete # ジョブを削除
└── proofreads
├── create # 最終レンダリング前に編集可能な字幕を抽出
├── get <id> # プルーフリードセッションのステータスを確認
├── srt get <id> # 抽出されたSRTをダウンロード
├── srt update <id> # 編集されたSRTをアップロード
└── generate <id> # 承認されたSRTから最終動画をレンダリング
heygen asset create --file <path> # ローカルソース動画のアップロード用(最大32 MB)
すべてのコマンドは --help をサポートしています。create コマンドで --request-schema を使用して完全なJSONボディを確認してください。CLI出力:JSONはstdoutに、{error:{code,message,hint}} エンベロープはstderrに、終了コード 0 OK · 1 API · 2 使用方法 · 3 認証 · 4 タイムアウト。create で --wait を追加すると、ジョブが完了するまでブロックします(デフォルトのタイムアウトは20分)。
📖 詳細なCLI/MCPエラー → アクションマッピング → references/troubleshooting.md
デフォルトワークフロー
このスキルは4つのフェーズで実行されます。フェーズ1(情報収集)は質問を行う唯一の場所です。フェーズ2(事前チェック)は非表示です。フェーズ3(送信+ポーリング)は非表示です。フェーズ4(結果提供)は1つの短いメッセージです。
フェーズ1 — 情報収集 — ユーザーから最低限必要な入力を収集
フェーズ2 — 事前チェック — 言語を検証、コンテンツを分類、フラグを設定
フェーズ3 — 送信+ポーリング — 開始、バックグラウンドポーリング、完了/失敗時のみ表示
フェーズ4 — 結果提供 — 1行の概要とともに結果を投稿
フェーズ1 — 情報収集
まだ持っていないものだけを尋ねてください。ユーザーの言語でコミュニケーションしてください。フォームを決して実行しないでください。 1ターンに1つか2つの質問、最大で。
必須入力(これらが揃うまでブロック):
- ソース動画。 公開URL、ローカルファイルパス、または以前のステップからのHeyGen asset_id。ユーザーがまだ提供していない場合は、尋ねます:「ソース動画は何ですか?URL、ファイルパス、または既存のHeyGenアセットですか?」
- ターゲット言語。 ユーザーの言語で自由形式の質問として尋ねます:「どの言語に翻訳しますか?」 ピッカーや事前に割り当てられた選択肢を提示しないでください — ユーザーが自由に入力できるようにしてください。ユーザーは1つの言語、複数の言語、または地域固有のバリエーションを希望する場合があります。指定されたものを受け入れ、フェーズ2で正規の言語リストに対して検証します。
重要な入力(提供されていない場合に尋ね、スマートなデフォルトを使用):
- 話者の数。 単一話者がデフォルトであり、ほとんどのユーザーが持つものです。曖昧な場合に一度尋ねます:「動画に何人の異なる話者がいますか?」 間違った話者数は品質を低下させる最大の原因です — 話者の混乱は翻訳途中での声の入れ替わりを引き起こします。複数人のコンテンツではこれを省略しないでください。
- コンテンツタイプ。 通常は尋ねる必要はありません — 動画から推測して確認します。以下の5つのプロファイルで約95%のケースをカバーします。本当に曖昧な場合のみ尋ねます。
- 字幕の設定。 トーキングヘッドや企業向けではデフォルトON。ポッドキャスト/音声のみではデフォルトOFF。デフォルトを変更した場合は、フェーズ4で簡単に言及します。
- 長さの柔軟性。 尋ねます:「翻訳された動画はオリジナルと完全に同じ長さである必要がありますか、それとも少し長く/短くなっても構いませんか?柔軟性を許容すると、通常はより自然に聞こえます — 翻訳された音声が、速められたり圧縮されたりする代わりに、快適なペースで話されるための十分な余地が得られます。」 デフォルトの推奨は柔軟(
enable_dynamic_duration: true)です。フレーム単位の正確なタイミング(タイムラインへの同期、広告枠、外部オーディオトラックなど)が必要な場合にのみfalseに設定します。
**オプション(関連する場合のみ尋ねます):
- 用語集 / 翻訳しない用語。 企業向けや技術的なコンテンツの場合、尋ねます:「元の言語のままにしておくべき製品名、会社名、または専門用語はありますか?」 HeyGenは現在、ハードな用語集を受け入れないため、これはステークが高い場合のプルーフリードステップ(フェーズ3-プルーフリード)のガイダンスになります。
- 部分的な翻訳。 ユーザーが特定のセグメント(「イントロだけ」「1:30から4:00まで」)に言及した場合、
start_timeとend_timeを秒単位で取得します。 - 最終レンダリング前にプルーフリードしますか? デフォルトOFF(より速く、承認が少ない)。デフォルトONは、長い動画(>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つすべてをユーザーにリストしないでください — 静かに提案し、ソースが本当に曖昧な場合(例:音楽が多いトーキングヘッドで、音声強調が役立つかどうか判断できない場合)のみ尋ねます。
| プロファイル | 使用する場合 | フラグ |
|---|---|---|
| トーキングヘッド / プレゼンター(デフォルト) | 一人がカメラに向かって話す。クリーンな音声。 | 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 |
| 音楽 / 高サウンドトラック | 背景音楽が音声を妨害する | 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。このプロファイルではプルーフリードを強く検討してください。 |
常に:
mode: "precision"ユーザーが明示的に「fast」/「quick」/「speed」を要求しない限り。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 (執筆時点では単一言語のみ):
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>, # 複数話者とわかっている場合のみ
)
CLI:
heygen video-translate create \
-d '{"video":{"type":"url","url":"https://..."},"output_languages":["Spanish (Spain)","Japanese (Japan)"]}' \
--mode precision \
--ena
…
[翻訳のため中略]