📦 Video Translate — 视频翻译与配音

将现有视频翻译并配音成多种语言，保留唇形同步和自然语音模式。提供视频 URL 或 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"}'

默认工作流

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

创建翻译任务

请求字段

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 {
  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"]

支持的语言

翻译选项

基础翻译（带唇形同步）

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 {
  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 {
  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 {
  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> {
  const results: Record = {};
  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 };
  }
}