Communitygithub.com

heygen-translate

將現有影片翻譯並配音成另一種語言,支援語音克隆和唇形同步(由 HeyGen 影片翻譯提供)。

heygen-translate 是什麼?

HeyGen 影片翻譯技能(heygen-translate)可讓 AI 代理將現有影片翻譯並配音成超過 175 種語言。它會保留原始講者的臉部與表演,克隆他們的語音到目標語言,並重新同步唇形,讓觀眾看到同樣的人以目標語言自然發言。此技能支援 HeyGen MCP 伺服器(用於單語言翻譯)和 HeyGen CLI(用於批次、多語言及校對工作流程)。關鍵功能包括語言自動偵測、內容設定檔分類(談話頭、podcast、音樂、多講者、企業),以及可選的校對步驟,讓使用者在最終渲染前檢視和編輯字幕。工作流程分為四個階段:發現(收集輸入)、預檢(驗證語言、影片來源、設定旗標)、提交與輪詢(背景處理)、以及交付(一個訊息回傳結果)。此技能是本地化行銷內容、教育課程、podcast 或任何需要讓原始講者流利說另一種語言影片的理想選擇,可為品牌一致性提供企業級語音克隆和精確的唇形同步。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Simo-Dax/claude-code-motion-video/tree/main/.claude/skills/heygen-translate

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

HeyGen 影片翻譯 (Video Translation)

將現有影片翻譯並配音成超過 175 種語言。系統會將講者的語音克隆到目標語言,重新同步唇形到新音訊,並回傳完整的配音影片。你提供來源影片和目標語言 — 引擎會處理轉錄、翻譯、語音克隆、唇形同步,以及(可選)嵌入字幕。

這不是生成新影片。原始影片中的講者、表演、取景和品牌資產都會保留。翻譯是在既有內容之上進行的。

使用者面向的行為

  1. 保持簡潔。 不要在對話中傾印翻譯 ID、原始 API 負載或狀態 JSON。報告結果(影片連結、語言),而不是底層機制。
  2. 不要使用內部術語。 不要說 "polling"、"video_translation_id"、"asset_id"、"v3 endpoint"。要說 "翻譯中"、"快完成了"、"你的檔案"。
  3. 輪詢是無聲的。 在背景處理長時間運行的翻譯,僅在 (a) 結果傳送、(b) 停滯超過 5 分鐘(一次更新)、(c) 硬性失敗時才告知。
  4. 一個結果,一則訊息。 影片完成時,傳送連結並附上一行摘要(目標語言、時長、模式)。不要列出每個 API 欄位。
  5. 不要說明傳輸選擇。 MCP、CLI 或 OpenClaw 外掛是內部實作。在 session 開始時靜默選擇;永遠不要提及正在使用哪一種。
  6. 使用使用者的語言溝通。 從使用者的第一則訊息偵測。回覆、確認和提問都使用他們的語言。技術性的 CLI/API 指令則保持英文。

API 模式偵測

在 session 開始時選擇一種傳輸方式。永遠不要混合使用、不要在 session 中途切換、也不要說明這個選擇。

依以下順序偵測:

  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,則繼續。如果退出碼非零(沒有金鑰、已過期、無效):
    1. 詢問使用者:「我需要你的 HeyGen API 金鑰才能繼續。你可以從 https://app.heygen.com/settings?nav=API 取得 — 請貼在這裡。」
    2. 一旦他們提供,將其持久化:echo "<key>" | heygen auth login(寫入 ~/.heygen/credentials,跨 session 保留)。
    3. 驗證: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 — 探索

只問你還缺少的資訊。使用使用者的語言溝通。永遠不要執行表單。 每次對話最多一兩個問題。

必要輸入(在取得這些之前持續詢問):

  1. 來源影片。 公開網址、本地檔案路徑,或先前步驟的 HeyGen asset_id。如果使用者尚未提供,詢問:「來源影片是什麼 — 一個網址、檔案路徑,還是既有的 HeyGen asset?」
  2. 目標語言。 以使用者的語言作為開放式問題詢問:「你想要翻譯成哪種語言?」不要提供挑選器或預先指定的選項 — 讓使用者自由輸入。他們可能想要一種語言、多種語言,或是一個特定地區的變體。接受他們提供的任何內容,並在階段 2 中根據標準語言列表進行驗證。

重要輸入(如果未提供則詢問,並帶有智慧型預設值):

  1. 講者人數。 單一講者是預設值,也是大多數使用者的情況。在語意不明時詢問一次:「影片中有多少個不同的講者?」講者人數錯誤是影響品質的第一大原因 — 講者混淆會在中途產生語音交換。對於多人內容,不要跳過這個問題。
  2. 內容類型。 你通常不需要詢問 — 從影片推斷並確認。以下五個設定檔涵蓋了約 95% 的情況。僅在真的無法確定時才詢問。
  3. 字幕偏好。 預設為開啟(針對談話頭和企業內容);預設為關閉(針對 podcast / 純音訊)。如果你更改了預設值,請在階段 4 中簡短提及。
  4. 時長靈活性。 詢問:「翻譯後的影片需要與原始影片完全相同的長度,還是可以稍長或稍短?允許靈活性通常會讓聽起來更自然 — 翻譯後的語音有足夠的空間以舒適的語速說出,而不是被加速或壓縮。」預設建議:靈活(enable_dynamic_duration: true)。僅在使用者需要影格精確的時間點(例如,同步到時間軸、廣告時段或外部音軌)時,才設為 false。聲調壓縮使得靈活性對於 en→zh、en→ja、en→ko(亞洲語言較短)、de→en、ja→en(較長)、ar/he/ur(從右至左 + 語域轉換)特別重要。

可選(僅在相關時詢問):

  1. 詞彙表 / 不翻譯的詞語。 對於企業或技術內容,詢問:「是否有任何產品名稱、公司名稱或行話需要保持原始語言?」HeyGen 目前不接受硬性的詞彙表,因此這會變成校對步驟(階段 3-校對)的指導方針,用於高風險的情況。
  2. 部分翻譯。 如果使用者提到特定片段(「只要開場」,「從 1:30 到 4:00」),請以秒為單位擷取 start_time 和 end_time。
  3. 最終渲染前要校對嗎? 預設為關閉(更快,需要較少的核准)。對於長影片(>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 分鐘)「翻譯正在進行,但花費的時間比預期長。我會繼續檢查 — 完成後我會通知你。」

參考資料

相關技能