HeyGen视频翻译API：多语言视频翻译配音，保持口型同步与自然语音

video-translate by heygen-com/skills

563 周安装量

92 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/heygen-com/skills --skill video-translate

AI/机器学习内容创作自动化

🇨🇳中文介绍

视频翻译 (HeyGen)

将现有视频翻译并配音为多种语言，保持口型同步和自然的语音模式。提供视频 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 下载翻译后的视频

创建翻译任务

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

字段	类型	必填	描述
`video_url`	string	Y*	要翻译的视频 URL (*或 `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		用于完成通知的 URL

语言	代码	备注
英语 (美国)	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 -X GET "https://api.heygen.com/v2/video_translate/{translate_id}" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

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: "额度不足" };
    }
    if (error.message.includes("duration")) {
      return { success: false, error: "视频过长" };
    }
    if (error.message.includes("format")) {
      return { success: false, error: "不支持的视频格式" };
    }
    return { success: false, error: error.message };
  }
}

🇺🇸English

Video Translation (HeyGen)

Translate and dub existing videos into multiple languages, preserving lip-sync and natural speech patterns. Provide a video URL or HeyGen video ID — no need to create the video on HeyGen first.

Authentication

All requests require the X-Api-Key header. Set the HEYGEN_API_KEY environment variable.

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"}'

Default Workflow

Provide a video URL or HeyGen video ID
Call POST /v2/video_translate with the target language
Poll GET /v2/video_translate/{translate_id} until status is completed
Download the translated video from the returned URL

Creating a Translation Job

Request Fields

Field	Type	Req	Description
`video_url`	string	Y*	URL of video to translate (*or `video_id`)
`video_id`	string	Y*	HeyGen video ID (*or `video_url`)
`output_language`	string	Y	Target language code (e.g., `"es-ES"`)

Either video_url or video_id must be provided.

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

Supported Languages

Language	Code	Notes
English (US)	en-US	Default source
Spanish (Spain)	es-ES	European Spanish
Spanish (Mexico)	es-MX	Latin American
French	fr-FR	Standard French
German	de-DE	Standard German
Italian	it-IT	Standard Italian
Portuguese (Brazil)	pt-BR	Brazilian Portuguese
Japanese	ja-JP	Standard Japanese
Korean	ko-KR	Standard Korean
Chinese (Mandarin)	zh-CN

Translation Options

Basic Translation (with lip-sync)

const config = {
  video_url: "https://example.com/original.mp4",
  output_language: "es-ES",
  title: "Spanish Translation",
};

Audio-Only Translation (faster, no lip-sync)

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

Multi-Speaker Videos

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

Advanced Options (v4 API)

For more control over translation:

interface VideoTranslateV4Request {
  input_video_id?: string;
  google_url?: string;
  output_languages: string[];        // Multiple languages in one call
  name: string;
  srt_key?: string;                  // Custom SRT subtitles
  instruction?: string;
  vocabulary?: string[];             // Terms to preserve as-is
  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;
}

Multiple Output Languages

const config = {
  input_video_id: "original_video_id",
  output_languages: ["es-ES", "fr-FR", "de-DE"],
  name: "Multi-language translations",
};

Custom Vocabulary (preserve specific terms)

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

Custom SRT Subtitles

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

Checking Translation Status

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;
}

Polling for Completion

Translations take longer than standard video generation — allow up to 30 minutes.

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");
}

Complete Workflow

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"
);

Batch Translation

Translate to multiple languages in parallel:

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"]
);

Features

Lip Sync — Automatically adjusts speaker's lip movements to match translated audio
Voice Cloning — Translated audio matches the original speaker's voice characteristics
Music Track Control — Optionally remove background music with disable_music_track: true
Speech Enhancement — Improve audio quality with enable_speech_enhancement: true

Best Practices

Source quality matters — Use high-quality source videos for better results
Clear audio — Videos with clear speech translate better
Single speaker — Best results with single-speaker content
Moderate pacing — Very fast speech may affect quality
Test first — Try with shorter clips before translating long videos
Allow extra time — Translation takes longer than video generation (up to 30 min)

Error Handling

Common errors and how to handle them:

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 };
  }
}

Weekly Installs

499

Repository

heygen-com/skills

GitHub Stars

First Seen

Mar 3, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

claude-code481

codex62

cursor62

gemini-cli61

kimi-cli61

opencode61

AI 代码实施计划编写技能 | 自动化开发任务分解与 TDD 流程规划工具

41,400 周安装

HeyGen视频翻译API：多语言视频翻译配音，保持口型同步与自然语音

🇨🇳中文介绍

视频翻译 (HeyGen)

身份验证

默认工作流程

创建翻译任务

相关 Skills

请求字段

curl

TypeScript

Python

支持的语言

翻译选项

基础翻译 (带口型同步)

仅音频翻译 (更快，无口型同步)

多说话者视频

高级选项 (v4 API)

多输出语言

自定义词汇表 (保留特定术语)

自定义 SRT 字幕

检查翻译状态

curl

TypeScript

轮询完成状态

完整工作流程

批量翻译

功能特性

最佳实践

错误处理

🇺🇸English

Video Translation (HeyGen)

Authentication

Default Workflow

Creating a Translation Job

Request Fields

curl

TypeScript

Python

Supported Languages

Translation Options

Basic Translation (with lip-sync)

Audio-Only Translation (faster, no lip-sync)

Multi-Speaker Videos

Advanced Options (v4 API)

Multiple Output Languages

Custom Vocabulary (preserve specific terms)

Custom SRT Subtitles

Checking Translation Status

curl

TypeScript

Polling for Completion

Complete Workflow

Batch Translation

Features

Best Practices

Error Handling

最新 Skills