影片翻譯 (HeyGen)
翻譯和配音現有影片成多種語言,保留唇形同步與自然語音模式。提供影片網址或 HeyGen 影片 ID — 無需先在 HeyGen 上建立影片。
驗證
所有請求都需要 X-Api-Key 標頭。設定 HEYGEN_API_KEY 環境變數。
curl -X POST "https://api.heygen.com/v2/video_translate" \
-H "X-Api-Key: $HEYGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"video_url": "https://example.com/video.mp4", "output_language": "es-ES"}'
預設工作流程
- 提供影片網址或 HeyGen 影片 ID
- 使用目標語言呼叫
POST /v2/video_translate - 輪詢
GET /v2/video_translate/{translate_id}直到狀態為completed - 從回傳的網址下載翻譯後的影片
建立翻譯任務
請求欄位
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
video_url | string | Y* | 要翻譯的影片網址(*或 video_id) |
video_id | string | Y* | HeyGen 影片 ID(*或 video_url) |
output_language | string | Y | 目標語言代碼(例如 "es-ES") |
title | string | 翻譯後影片的名稱 | |
translate_audio_only | boolean | 僅音訊,無唇形同步(較快) | |
speaker_num | number | 影片中的說話者人數 | |
callback_id | string | 用於 Webhook 追蹤的自訂 ID | |
callback_url | string | 完成通知的網址 |
必須提供 video_url 或 video_id 其中一項。
curl
curl -X POST "https://api.heygen.com/v2/video_translate" \
-H "X-Api-Key: $HEYGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://example.com/original-video.mp4",
"output_language": "es-ES",
"title": "Spanish Version"
}'
TypeScript
interface VideoTranslateRequest {
video_url?: string;
video_id?: string;
output_language: string;
title?: string;
translate_audio_only?: boolean;
speaker_num?: number;
callback_id?: string;
callback_url?: string;
}
interface VideoTranslateResponse {
error: null | string;
data: {
video_translate_id: string;
};
}
async function translateVideo(config: VideoTranslateRequest): Promise<string> {
const response = await fetch("https://api.heygen.com/v2/video_translate", {
method: "POST",
headers: {
"X-Api-Key": process.env.HEYGEN_API_KEY!,
"Content-Type": "application/json",
},
body: JSON.stringify(config),
});
const json: VideoTranslateResponse = await response.json();
if (json.error) {
throw new Error(json.error);
}
return json.data.video_translate_id;
}
Python
import requests
import os
def translate_video(config: dict) -> str:
response = requests.post(
"https://api.heygen.com/v2/video_translate",
headers={
"X-Api-Key": os.environ["HEYGEN_API_KEY"],
"Content-Type": "application/json"
},
json=config
)
data = response.json()
if data.get("error"):
raise Exception(data["error"])
return data["data"]["video_translate_id"]
支援的語言
| 語言 | 代碼 | 備註 |
|---|---|---|
| 英語(美國) | en-US | 預設來源語言 |
| 西班牙語(西班牙) | es-ES | 歐洲西班牙語 |
| 西班牙語(墨西哥) | es-MX | 拉丁美洲 |
| 法語 | fr-FR | 標準法語 |
| 德語 | de-DE | 標準德語 |
| 義大利語 | it-IT | 標準義大利語 |
| 葡萄牙語(巴西) | pt-BR | 巴西葡語 |
| 日語 | ja-JP | 標準日語 |
| 韓語 | ko-KR | 標準韓語 |
| 中文(普通話) | zh-CN | 簡體中文 |
| 印地語 | hi-IN | 標準印地語 |
| 阿拉伯語 | ar-SA | 現代標準阿拉伯語 |
翻譯選項
基本翻譯(含唇形同步)
const config = {
video_url: "https://example.com/original.mp4",
output_language: "es-ES",
title: "Spanish Translation",
};
純音訊翻譯(較快,無唇形同步)
const config = {
video_url: "https://example.com/original.mp4",
output_language: "es-ES",
translate_audio_only: true,
};
多位說話者影片
const config = {
video_url: "https://example.com/interview.mp4",
output_language: "fr-FR",
speaker_num: 2,
};
進階選項(v4 API)
如需更多翻譯控制:
interface VideoTranslateV4Request {
input_video_id?: string;
google_url?: string;
output_languages: string[]; // 一次呼叫多種語言
name: string;
srt_key?: string; // 自訂 SRT 字幕
instruction?: string;
vocabulary?: string[]; // 保留不翻譯的詞彙
brand_voice_id?: string;
speaker_num?: number;
keep_the_same_format?: boolean;
input_language?: string;
enable_video_stretching?: boolean;
disable_music_track?: boolean;
enable_speech_enhancement?: boolean;
srt_role?: "input" | "output";
translate_audio_only?: boolean;
}
多種輸出語言
const config = {
input_video_id: "original_video_id",
output_languages: ["es-ES", "fr-FR", "de-DE"],
name: "Multi-language translations",
};
自訂詞彙(保留特定詞彙)
const config = {
video_url: "https://example.com/product-demo.mp4",
output_language: "ja-JP",
vocabulary: ["SuperWidget", "Pro Max", "TechCorp"],
};
自訂 SRT 字幕
const config = {
video_url: "https://example.com/video.mp4",
output_language: "es-ES",
srt_key: "path/to/custom-subtitles.srt",
srt_role: "input",
};
檢查翻譯狀態
curl
curl -X GET "https://api.heygen.com/v2/video_translate/{translate_id}" \
-H "X-Api-Key: $HEYGEN_API_KEY"
TypeScript
interface TranslateStatusResponse {
error: null | string;
data: {
id: string;
status: "pending" | "processing" | "completed" | "failed";
video_url?: string;
message?: string;
};
}
async function getTranslateStatus(translateId: string): Promise<TranslateStatusResponse["data"]> {
const response = await fetch(
`https://api.heygen.com/v2/video_translate/${translateId}`,
{ headers: { "X-Api-Key": process.env.HEYGEN_API_KEY! } }
);
const json: TranslateStatusResponse = await response.json();
if (json.error) {
throw new Error(json.error);
}
return json.data;
}
輪詢等待完成
翻譯比標準影片生成需要更長時間 — 最多允許 30 分鐘。
async function waitForTranslation(
translateId: string,
maxWaitMs = 1800000,
pollIntervalMs = 30000
): Promise<string> {
const startTime = Date.now();
while (Date.now() - startTime < maxWaitMs) {
const status = await getTranslateStatus(translateId);
switch (status.status) {
case "completed":
return status.video_url!;
case "failed":
throw new Error(status.message || "Translation failed");
default:
console.log(`Status: ${status.status}...`);
await new Promise((r) => setTimeout(r, pollIntervalMs));
}
}
throw new Error("Translation timed out");
}
完整工作流程
async function translateAndDownload(
videoUrl: string,
targetLanguage: string
): Promise<string> {
console.log(`Starting translation to ${targetLanguage}...`);
const translateId = await translateVideo({
video_url: videoUrl,
output_language: targetLanguage,
});
console.log(`Translation ID: ${translateId}`);
console.log("Processing translation...");
const translatedVideoUrl = await waitForTranslation(translateId);
console.log(`Translation complete: ${translatedVideoUrl}`);
return translatedVideoUrl;
}
const spanishVideo = await translateAndDownload(
"https://example.com/my-video.mp4",
"es-ES"
);
批次翻譯
平行翻譯成多種語言:
async function translateToMultipleLanguages(
sourceVideoUrl: string,
targetLanguages: string[]
): Promise<Record<string, string>> {
const results: Record<string, string> = {};
const translatePromises = targetLanguages.map(async (lang) => {
const translateId = await translateVideo({
video_url: sourceVideoUrl,
output_language: lang,
});
return { lang, translateId };
});
const translationJobs = await Promise.all(translatePromises);
for (const job of translationJobs) {
try {
const videoUrl = await waitForTranslation(job.translateId);
results[job.lang] = videoUrl;
} catch (error) {
results[job.lang] = `error: ${error.message}`;
}
}
return results;
}
const translations = await translateToMultipleLanguages(
"https://example.com/original.mp4",
["es-ES", "fr-FR", "de-DE", "ja-JP"]
);
功能特色
- 唇形同步 — 自動調整說話者的嘴唇動作以匹配翻譯後的音訊
- 語音複製 — 翻譯後的音訊保留原始說話者的聲音特徵
- 音樂音軌控制 — 可選用
disable_music_track: true移除背景音樂 - 語音增強 — 使用
enable_speech_enhancement: true改善音訊品質
最佳做法
- 來源品質重要 — 使用高品質來源影片以獲得更好結果
- 清晰音訊 — 說話清晰的影片翻譯效果更好
- 單一說話者 — 單一說話者內容效果最佳
- 適中節奏 — 語速過快可能影響品質
- 先測試 — 在翻譯長影片前先用短片試試
- 預留時間 — 翻譯比影片生成耗時更長(最多 30 分鐘)
錯誤處理
常見錯誤及其處理方式:
async function safeTranslate(
videoUrl: string,
targetLanguage: string
): Promise<{ success: boolean; result?: string; error?: string }> {
try {
const url = await translateAndDownload(videoUrl, targetLanguage);
return { success: true, result: url };
} catch (error) {
if (error.message.includes("quota")) {
return { success: false, error: "Insufficient credits" };
}
if (error.message.includes("duration")) {
return { success: false, error: "Video too long" };
}
if (error.message.includes("format")) {
return { success: false, error: "Unsupported video format" };
}
return { success: false, error: error.message };
}
}