HeyGen 影片翻譯 (Video Translation)
將現有影片翻譯並配音成超過 175 種語言。系統會將講者的語音克隆到目標語言,重新同步唇形到新音訊,並回傳完整的配音影片。你提供來源影片和目標語言 — 引擎會處理轉錄、翻譯、語音克隆、唇形同步,以及(可選)嵌入字幕。
這不是生成新影片。原始影片中的講者、表演、取景和品牌資產都會保留。翻譯是在既有內容之上進行的。
使用者面向的行為
- 保持簡潔。 不要在對話中傾印翻譯 ID、原始 API 負載或狀態 JSON。報告結果(影片連結、語言),而不是底層機制。
- 不要使用內部術語。 不要說 "polling"、"video_translation_id"、"asset_id"、"v3 endpoint"。要說 "翻譯中"、"快完成了"、"你的檔案"。
- 輪詢是無聲的。 在背景處理長時間運行的翻譯,僅在 (a) 結果傳送、(b) 停滯超過 5 分鐘(一次更新)、(c) 硬性失敗時才告知。
- 一個結果,一則訊息。 影片完成時,傳送連結並附上一行摘要(目標語言、時長、模式)。不要列出每個 API 欄位。
- 不要說明傳輸選擇。 MCP、CLI 或 OpenClaw 外掛是內部實作。在 session 開始時靜默選擇;永遠不要提及正在使用哪一種。
- 使用使用者的語言溝通。 從使用者的第一則訊息偵測。回覆、確認和提問都使用他們的語言。技術性的 CLI/API 指令則保持英文。
API 模式偵測
在 session 開始時選擇一種傳輸方式。永遠不要混合使用、不要在 session 中途切換、也不要說明這個選擇。
依以下順序偵測:
- 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,則繼續。如果退出碼非零(沒有金鑰、已過期、無效):- 詢問使用者:「我需要你的 HeyGen API 金鑰才能繼續。你可以從 https://app.heygen.com/settings?nav=API 取得 — 請貼在這裡。」
- 一旦他們提供,將其持久化:
echo "<key>" | heygen auth login(寫入~/.heygen/credentials,跨 session 保留)。 - 驗證:
heygen auth status。如果仍然失敗,顯示錯誤並停止。
這是一次性設定。一旦 heygen auth login 持久化了金鑰,未來的 session 會自動使用它。如果 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來查看任何 create 命令的完整 JSON 格式。 - 以下操作並列顯示 MCP 和 CLI — 只閱讀你偵測到模式的對應欄位。
MCP 工具名稱(僅 MCP 模式)
create_video_translation(單語言)。多語言和校對功能目前尚未透過 MCP 暴露 — 這些情況請退回到 CLI。在 session 開始時執行 mcp__heygen__* 工具列表來確認有哪些可用;工具功能表會持續演進。
CLI 命令群組(僅 CLI 模式)
heygen video-translate
├── languages list # 列出支援的目標語言
├── create # 提交翻譯任務(單一或批次)
├── get <id> # 檢查狀態 / 取得結果
├── list # 列出過去的翻譯
├── update # 更新任務後設資料
├── delete # 刪除任務
└── proofreads
├── create # 在最終渲染前提取可編輯的字幕
├── get <id> # 檢查校對 session 狀態
├── 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 正常 · 1 API 錯誤 · 2 使用方式錯誤 · 3 認證錯誤 · 4 超時。在 create 上加上 --wait 來阻塞直到任務完成(預設超時 20 分鐘)。
📖 詳細的 CLI/MCP 錯誤 → 動作對應表 → references/troubleshooting.md
預設工作流程
此技能執行四個階段。階段 1(探索)是唯一可以提問的地方。階段 2(預檢)是靜默的。階段 3(提交 + 輪詢)是靜默的。階段 4(交付)是一則簡短訊息。
階段 1 — 探索 — 從使用者收集最小必要輸入
階段 2 — 預檢 — 驗證語言、分類內容、設定旗標
階段 3 — 提交 + 輪詢 — 啟動、背景輪詢,僅在完成/失敗時告知
階段 4 — 交付 — 以一行的摘要張貼結果
階段 1 — 探索
只問你還缺少的資訊。使用使用者的語言溝通。永遠不要執行表單。 每次對話最多一兩個問題。
必要輸入(在取得這些之前持續詢問):
- 來源影片。 公開網址、本地檔案路徑,或先前步驟的 HeyGen asset_id。如果使用者尚未提供,詢問:「來源影片是什麼 — 一個網址、檔案路徑,還是既有的 HeyGen asset?」
- 目標語言。 以使用者的語言作為開放式問題詢問:「你想要翻譯成哪種語言?」不要提供挑選器或預先指定的選項 — 讓使用者自由輸入。他們可能想要一種語言、多種語言,或是一個特定地區的變體。接受他們提供的任何內容,並在階段 2 中根據標準語言列表進行驗證。
重要輸入(如果未提供則詢問,並帶有智慧型預設值):
- 講者人數。 單一講者是預設值,也是大多數使用者的情況。在語意不明時詢問一次:「影片中有多少個不同的講者?」講者人數錯誤是影響品質的第一大原因 — 講者混淆會在中途產生語音交換。對於多人內容,不要跳過這個問題。
- 內容類型。 你通常不需要詢問 — 從影片推斷並確認。以下五個設定檔涵蓋了約 95% 的情況。僅在真的無法確定時才詢問。
- 字幕偏好。 預設為開啟(針對談話頭和企業內容);預設為關閉(針對 podcast / 純音訊)。如果你更改了預設值,請在階段 4 中簡短提及。
- 時長靈活性。 詢問:「翻譯後的影片需要與原始影片完全相同的長度,還是可以稍長或稍短?允許靈活性通常會讓聽起來更自然 — 翻譯後的語音有足夠的空間以舒適的語速說出,而不是被加速或壓縮。」預設建議:靈活(
enable_dynamic_duration: true)。僅在使用者需要影格精確的時間點(例如,同步到時間軸、廣告時段或外部音軌)時,才設為false。聲調壓縮使得靈活性對於 en→zh、en→ja、en→ko(亞洲語言較短)、de→en、ja→en(較長)、ar/he/ur(從右至左 + 語域轉換)特別重要。
可選(僅在相關時詢問):
- 詞彙表 / 不翻譯的詞語。 對於企業或技術內容,詢問:「是否有任何產品名稱、公司名稱或行話需要保持原始語言?」HeyGen 目前不接受硬性的詞彙表,因此這會變成校對步驟(階段 3-校對)的指導方針,用於高風險的情況。
- 部分翻譯。 如果使用者提到特定片段(「只要開場」,「從 1:30 到 4:00」),請以秒為單位擷取
start_time和end_time。 - 最終渲染前要校對嗎? 預設為關閉(更快,需要較少的核准)。對於長影片(>3 分鐘)、企業/品牌內容、高風險的法律/醫療/教育內容,以及使用者能閱讀的語言(以便他們可以驗證),預設為開啟。詢問:「你想在最終渲染前檢視和編輯字幕嗎?這會多花約 5 分鐘,但可以讓你修正任何錯誤的詞語。」
📖 語言組別的注意事項(語域、從右至左語言、聲調壓縮、唇形同步上限)→ references/language-locale-guide.md
階段 2 — 預檢
靜默。不對使用者發布訊息。依序進行三項檢查。
檢查 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 網址(無需認證,HEAD 請求回傳影片 MIME 類型) | 直接傳遞為 {type: "url", url: "..."} |
| 需要認證的網址、403、404 或 HTML 回應 | 告知使用者,要求提供公開網址或本地檔案 |
| 本地檔案路徑 | 透過 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: "..."} |
📖 資產路由邊緣情況(非常大的檔案、預先簽署的網址、需要認證的來源)→ references/asset-routing.md
檢查 2c:內容設定檔。
根據來源選擇一個設定檔。不要向使用者列出所有五個 — 靜默地提出,並僅在來源真的不明確時才詢問(例如,一個音樂很重的談話頭影片,你無法判斷語音增強是否有幫助)。
| 設定檔 | 使用時機 | 旗標 |
|---|---|---|
| 談話頭 / 講者(預設) | 一個人對著鏡頭說話;音訊乾淨 | mode: precision、enable_speech_enhancement: true、enable_caption: true、enable_dynamic_duration: true、keep_the_same_format: true |
| Podcast / 純音訊 | 畫面是靜態的、不重要或不存在 | 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 |
| 多講者 | 有兩個或更多不同的講者 | 談話頭的預設值 + speaker_num: <count>。此處必須提供講者人數 — 不要猜測。 |
| 企業 / 品牌內容 | 品牌語調、詞彙表紀律、高風險 | 談話頭的預設值 + (如果使用者有)brand_voice_id。對於此設定檔,強烈考慮使用校對功能。 |
始終設定:
mode: "precision",除非使用者明確要求「快速」/「迅速」/「速度」。enable_dynamic_duration:根據使用者在階段 1 中對時長靈活性問題的回答來設定。預設為true(推薦)— 讓翻譯後的語音有空間呼吸,而不是被塞進來源的精確時間點。僅在使用者明確需要固定長度的輸出時才設為false。聲調壓縮使得靈活性對於 en→zh、en→ja、en→ko(亞洲語言較短)、de→en、ja→en(較長)、ar/he/ur(從右至左 + 語域轉換)特別重要。keep_the_same_format: true用於視覺翻譯 — 保留來源的解析度和位元率,使配音後的影片與原始編碼相符。enable_watermark: false(預設值)。
階段 3 — 提交 + 輪詢
靜默。背景工作。僅在 (a) 每種語言完成、(b) 每種語言硬性失敗、(c) 超過 5 分鐘進度檢查時才告知。
分支:
- 標準路徑(校對 = 關閉):提交翻譯、背景輪詢、交付。
- 校對路徑(校對 = 開啟):建立校對 session → 下載 SRT → 使用者編輯或你協助 → 上傳編輯過的 SRT → 生成最終影片 → 背景輪詢 → 交付。
標準路徑
使用批次語法為每個目標語言提交一個任務(--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 \
--enable_speech_enhancement \
--enable_caption \
--enable_dynamic_duration \
--keep_the_same_format \
--speaker_num 1 \
--wait
校對路徑
對於校對 = 開啟的情況,使用支援的結構:
# 1. 建立校對 session(提取字幕,不渲染)
heygen video-translate proofreads create \
-d '{"video":{"type":"url","url":"https://..."},"output_languages":["Spanish (Spain)"]}' \
--mode precision \
--wait
# 2. 取得 proofread_id 後,下載 SRT
heygen video-translate proofreads srt get <proofread_id> -l "Spanish (Spain)" > subtitles.srt
# 3. 使用者編輯或 AI 協助修改 SRT(顯示差異,提出修正)
# 4. 上傳編輯過的 SRT
heygen video-translate proofreads srt update <proofread_id> -l "Spanish (Spain)" -f edited_subtitles.srt
# 5. 根據已核准的 SRT 生成最終影片
heygen video-translate proofreads generate <proofread_id> --wait
MCP 注意事項: 如果 create_video_translation 不可用於校對,請退回到 CLI 用於校對操作。
階段 4 — 交付
對於每種完成的語言,發送一則單一、乾淨的訊息:
完成的翻譯: [語言名稱] 影片連結: [HeyGen 影片 URL] 時長: [原始時長] → [翻譯後時長] 模式: 精確配音 字幕: 已嵌入
如果 enable_dynamic_duration 為 true,則在時長行中注意差異(「由於靈活的時長控制,為了自然發音,稍有延長/縮短」)。
如果校對了字幕,加入:「字幕已根據你的編輯進行了審閱和核准。」
永遠不要在結果中顯示 video_translation_id、status JSON 或其他內部欄位。使用者看到的是影片,而不是 API 回應。
錯誤處理
| 情境 | 使用者看到的內容 |
|---|---|
| 不支援的語言 | 「抱歉,[語言] 不在支援的語言中。最接近的選項是 [lang1]、[lang2] — 哪一個是正確的?」 |
| 影片載入失敗 | 「我無法存取該影片。請確保它是一個公開的影片 URL 或本地檔案。」 |
| 講者偵測失敗 | 「我無法確定影片中的講者人數。大約有多少人說話?」 |
| 字幕校對逾時 | 「字幕校對階段花費的時間比預期長。你想繼續並使用目前為止的字幕進行渲染嗎?」 |
| API 錯誤(CLI) | 顯示 error.message 和 error.hint(如果存在)。如果 error.code 是 401/403:「請重新認證 HeyGen:heygen auth login」 |
| 一般超時(20 分鐘) | 「翻譯正在進行,但花費的時間比預期長。我會繼續檢查 — 完成後我會通知你。」 |