视频翻译 (HeyGen)

翻译并配音现有视频为多种语言，保持唇形同步和自然语音模式。提供视频URL或HeyGen视频ID — 无需先在HeyGen上创建视频。

身份验证

所有请求都需要X-Api-Key请求头。设置HEYGENAPIKEY环境变量。

bash
curl -X POST https://api.heygen.com/v2/video_translate \
-H X-Api-Key: $HEYGENAPIKEY \
-H Content-Type: application/json \
-d {videourl: https://example.com/video.mp4, outputlanguage: es-ES}

默认工作流程

1. 1. 提供视频URL或HeyGen视频ID
2. 使用目标语言调用POST /v2/videotranslate
3. 轮询GET /v2/videotranslate/{translate_id}直到状态为completed
4. 从返回的URL下载翻译后的视频

创建翻译任务

请求字段

必须提供videourl或videoid之一。

curl

bash
curl -X POST https://api.heygen.com/v2/video_translate \
-H X-Api-Key: $HEYGENAPIKEY \
-H Content-Type: application/json \
-d {
video_url: https://example.com/original-video.mp4,
output_language: es-ES,
title: 西班牙语版本
}

TypeScript

typescript
interface VideoTranslateRequest {
video_url?: string;
video_id?: string;
output_language: string;
title?: string;
translateaudioonly?: boolean;
speaker_num?: number;
callback_id?: string;
callback_url?: string;
}

interface VideoTranslateResponse {
error: null | string;
data: {
videotranslateid: string;
};
}

async function translateVideo(config: VideoTranslateRequest): Promise {
const response = await fetch(https://api.heygen.com/v2/video_translate, {
method: POST,
headers: {
X-Api-Key: process.env.HEYGENAPIKEY!,
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.videotranslateid;
}

Python

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[HEYGENAPIKEY],
Content-Type: application/json
},
json=config
)

data = response.json()
if data.get(error):
raise Exception(data[error])

return data[data][videotranslateid]

支持的语言

翻译选项

基础翻译（带唇形同步）

typescript
const config = {
video_url: https://example.com/original.mp4,
output_language: es-ES,
title: 西班牙语翻译,
};

仅音频翻译（更快，无唇形同步）

typescript
const config = {
video_url: https://example.com/original.mp4,
output_language: es-ES,
translateaudioonly: true,
};

多说话人视频

typescript
const config = {
video_url: https://example.com/interview.mp4,
output_language: fr-FR,
speaker_num: 2,
};

高级选项（v4 API）

更精细地控制翻译：

typescript
interface VideoTranslateV4Request {
inputvideoid?: string;
google_url?: string;
output_languages: string[]; // 一次调用多种语言
name: string;
srt_key?: string; // 自定义SRT字幕
instruction?: string;
vocabulary?: string[]; // 保留原样的术语
brandvoiceid?: string;
speaker_num?: number;
keepthesame_format?: boolean;
input_language?: string;
enablevideostretching?: boolean;
disablemusictrack?: boolean;
enablespeechenhancement?: boolean;
srt_role?: input | output;
translateaudioonly?: boolean;
}

多输出语言

typescript
const config = {
inputvideoid: originalvideoid,
output_languages: [es-ES, fr-FR, de-DE],
name: 多语言翻译,
};

自定义词汇表（保留特定术语）

typescript
const config = {
video_url: https://example.com/product-demo.mp4,
output_language: ja-JP,
vocabulary: [SuperWidget, Pro Max, TechCorp],
};

自定义SRT字幕

typescript
const config = {
video_url: https://example.com/video.mp4,
output_language: es-ES,
srt_key: path/to/custom-subtitles.srt,
srt_role: input,
};

检查翻译状态

curl

bash
curl -X GET https://api.heygen.com/v2/videotranslate/{translateid} \
-H X-Api-Key: $HEYGENAPIKEY

TypeScript

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 {
const response = await fetch(
https://api.heygen.com/v2/video_translate/${translateId},
{ headers: { X-Api-Key: process.env.HEYGENAPIKEY! } }
);

const json: TranslateStatusResponse = await response.json();

if (json.error) {
throw new Error(json.error);
}

return json.data;
}

轮询完成状态

翻译比标准视频生成耗时更长 — 最多等待30分钟。

typescript
async function waitForTranslation(
translateId: string,
maxWaitMs = 1800000,
pollIntervalMs = 30000
): Promise {
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 || 翻译失败);
default:
console.log(状态: ${status.status}...);
await new Promise((r) => setTimeout(r, pollIntervalMs));
}
}

throw new Error(翻译超时);
}

完整工作流程

typescript
async function translateAndDownload(