video-translate Checked

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 | Simplified Chinese |
| Hindi | hi-IN | Standard Hindi |
| Arabic | ar-SA | Modern Standard Arabic |

## 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 tran