Video Translation

Mode: "speed" (default) Best for: fast turnaround, batch jobs, and workflows where time matters more than perfect lip-sync. For higher fidelity at the cost of latency, see Precision mode. For dozens or hundreds of videos in one job, see Video Translation batches.

How Lip Sync and Video Translation Relate

Both APIs sit on top of one lip sync engine that runs in two modes — Speed and Precision — trading latency for fidelity. What differs is what each API does around that engine:

Lip Sync API — the engine on its own. You bring the video and your own audio; the engine redraws the mouth to match. No translation, no audio generation — dialogue replacement only.
Video Translation API — translation, optionally followed by the engine. It has two output modes:
- Audio only (translate_audio_only: true) — transcribe, translate, and generate the translated audio, then stop. No lip sync. The output is just the new audio track (or the original video with swapped audio and an untouched mouth).
- Video (audio + visual) — the same translation pipeline, then runs the lip sync engine so the mouth matches the translated speech.

The short version:

Lip Sync API = engine only — you bring the audio.
Video Translation API = translation, optionally followed by the engine. Audio-only mode skips the engine entirely; video mode adds it back.

Quick Start

1. List Supported Languages

Before translating, fetch the available target language codes via GET /v3/video-translations/languages:

curl --request GET \
  --url 'https://api.heygen.com/v3/video-translations/languages' \
  --header 'accept: application/json' \
  --header 'x-api-key: <your-api-key>'

2. Submit a Translation (Single Language)

Full schema: POST /v3/video-translations.

curl --request POST \
  --url 'https://api.heygen.com/v3/video-translations' \
  --header 'accept: application/json' \
  --header 'x-api-key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "video": {
      "type": "url",
      "url": "<video_url>"
    },
    "output_languages": ["Spanish"],
    "mode": "speed",
    "title": "My Translated Video"
  }'

Batch (Multiple Languages)

Translate into several languages in one request:

curl --request POST \
  --url 'https://api.heygen.com/v3/video-translations' \
  --header 'accept: application/json' \
  --header 'x-api-key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "video": {
      "type": "url",
      "url": "<video_url>"
    },
    "output_languages": ["English", "Spanish", "French"],
    "mode": "speed",
    "title": "Global Campaign"
  }'

Response returns one ID per language:

{
  "data": {
    "video_translation_ids": [
      "tr_abc123-en",
      "tr_abc123-es",
      "tr_abc123-fr"
    ]
  }
}

3. Poll for Status

Use GET /v3/video-translations/{video_translation_id}. Skip polling by passing callback_url — see Webhooks.

curl --request GET \
  --url 'https://api.heygen.com/v3/video-translations/<video_translation_id>' \
  --header 'accept: application/json' \
  --header 'x-api-key: <your-api-key>'

Status	Meaning
`pending`	Queued
`running`	In progress
`completed`	Done — `video_url` is available
`failed`	Check `failure_message`

Source Video Input

Type	Example
URL	`{ "type": "url", "url": "https://example.com/video.mp4" }`
Asset ID	`{ "type": "asset_id", "asset_id": "<asset_id>" }`

The URL must be publicly accessible (test by opening in an incognito browser). To use an asset_id, upload first via POST /v3/assets — see the Upload Assets guide.

Speed Mode Options

These parameters are particularly relevant for Speed mode:

Parameter	Default	Description
`mode`	`"speed"`	Set to `"speed"` for faster processing
`speaker_num`	auto	Number of speakers
`translate_audio_only`	`false`	When `true`, only audio is translated; original video is preserved
`enable_dynamic_duration`	`true`	Allows output duration to vary to match natural speech pacing
`disable_music_track`	`false`	Strips background music from output
`enable_speech_enhancement`	`false`	Improves speech audio quality
`enable_caption`	`false`	Generates captions alongside the video
`brand_glossary_id`	—	Apply a brand glossary so your product names and custom terms survive the translation intact
`brand_voice_id`	—	Deprecated. The former name for `brand_glossary_id`; both are accepted and resolve to the same glossary
`callback_url`	—	Webhook URL notified on completion or failure
`callback_id`	—	Your own ID, echoed back in the webhook payload

Stock Voice (Enterprise)

Use a preset “stock” voice for the translation instead of recreating the original speaker’s voice. By default, Video Translation clones the original speaker, so the translated video sounds like them. With this option enabled, the translation is spoken by a natural, preset voice that’s optimized for clear pronunciation and accent in the target language. The trade-off: the result won’t sound like the original speaker.

This is an Enterprise feature, available for selected accounts and languages and turned on by request. To use it, contact your HeyGen account team.

Pass stock_voice_config in the translation request:

Field	Type	Default	Description
`use_stock_voice`	boolean	`false`	Set to `true` to use a preset stock voice instead of cloning the original speaker.
`preferred_stock_voice_ids`	string[]	—	Optional. Pin specific stock voices to draw from. Each entry is a Gemini voice name (e.g. `Erinome`, `Vindemiatrix`), not a UUID. If omitted, the target language’s default stock-voice pool is used.

curl --request POST \
  --url 'https://api.heygen.com/v3/video-translations' \
  --header 'accept: application/json' \
  --header 'x-api-key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "video": {
      "type": "url",
      "url": "<video_url>"
    },
    "output_languages": ["Spanish"],
    "mode": "speed",
    "title": "My Translated Video",
    "stock_voice_config": {
      "use_stock_voice": true,
      "preferred_stock_voice_ids": ["Erinome"]
    }
  }'

Captions

To enable captions, set enable_caption: true in the translation request. Once completed, download them:

curl --request GET \
  --url 'https://api.heygen.com/v3/video-translations/<video_translation_id>/caption?format=srt' \
  --header 'accept: application/json' \
  --header 'x-api-key: <your-api-key>'

Supported formats: srt, vtt.

Proofread Before Finalizing

Speed mode supports the proofread workflow — review and edit subtitles before spending credits on final generation. Reference: Create · Get · Download SRT · Upload SRT · Generate Final Video.

Step 1 — Create Proofread Session

Full schema: POST /v3/video-translations/proofreads.

curl --request POST \
  --url 'https://api.heygen.com/v3/video-translations/proofreads' \
  --header 'x-api-key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "video": { "type": "url", "url": "<video_url>" },
    "output_languages": ["Spanish"],
    "title": "Review Before Publishing",
    "mode": "speed"
  }'

Returns proofread_ids — one per language.

Step 2 — Poll Until `completed`

GET /v3/video-translations/proofreads/{proofread_id}.

curl --request GET \
  --url 'https://api.heygen.com/v3/video-translations/proofreads/<proofread_id>' \
  --header 'x-api-key: <your-api-key>'

Step 3 — Download & Edit the SRT

Download via GET /v3/video-translations/proofreads/{proofread_id}/srt; upload the revised file via Upload Proofread SRT.

curl --request GET \
  --url 'https://api.heygen.com/v3/video-translations/proofreads/<proofread_id>/srt' \
  --header 'x-api-key: <your-api-key>'

Edit the returned srt_url file locally, then upload the revised version:

curl --request PUT \
  --url 'https://api.heygen.com/v3/video-translations/proofreads/<proofread_id>/srt' \
  --header 'x-api-key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{ "srt": { "type": "url", "url": "<your_edited_srt_url>" } }'

Step 4 — Generate Final Video

POST /v3/video-translations/proofreads/{proofread_id}/generate.

curl --request POST \
  --url 'https://api.heygen.com/v3/video-translations/proofreads/<proofread_id>/generate' \
  --header 'x-api-key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{ "captions": true }'

Returns a video_translation_id to poll via GET /v3/video-translations/{video_translation_id}.

Other Operations

List All Translations

GET /v3/video-translations.

curl --request GET \
  --url 'https://api.heygen.com/v3/video-translations?limit=10' \
  --header 'x-api-key: <your-api-key>'

Uses has_more + next_token for pagination.

Delete a Translation

DELETE /v3/video-translations/{video_translation_id}.

curl --request DELETE \
  --url 'https://api.heygen.com/v3/video-translations/<video_translation_id>' \
  --header 'x-api-key: <your-api-key>'

When to Use Speed vs. Precision

	Speed	Precision
Processing Time	Faster	Slower
Translation	Adequate	Context- and Gender-Aware
Lip-Sync Quality	Standard	High
Best For	Faces with little movement, quick drafts	Faces with significant movement, side angles, or occlusions; final delivery videos

For high-volume jobs across many source videos, see Video Translation batches.

Auth

User Info

Models

Video Generation

Video Composition

On Brand

Realtime Video

Lipsync

Tools

Avatar Management

Voice Management

Asset Management

Batches

Webhook

Limits

Pricing

Socials

For Agents

Integrations

Video Translation - Speed

How Lip Sync and Video Translation Relate

Quick Start

1. List Supported Languages

2. Submit a Translation (Single Language)

Batch (Multiple Languages)

3. Poll for Status

Source Video Input

Speed Mode Options

Stock Voice (Enterprise)

Captions

Proofread Before Finalizing

Step 1 — Create Proofread Session

Step 2 — Poll Until `completed`

Step 3 — Download & Edit the SRT

Step 4 — Generate Final Video

Other Operations

List All Translations

Delete a Translation

When to Use Speed vs. Precision

​How Lip Sync and Video Translation Relate

​Quick Start

​1. List Supported Languages

​2. Submit a Translation (Single Language)

​Batch (Multiple Languages)

​3. Poll for Status

​Source Video Input

​Speed Mode Options

​Stock Voice (Enterprise)

​Captions

​Proofread Before Finalizing

​Step 1 — Create Proofread Session

​Step 2 — Poll Until completed

​Step 3 — Download & Edit the SRT

​Step 4 — Generate Final Video

​Other Operations

​List All Translations

​Delete a Translation

​When to Use Speed vs. Precision

How Lip Sync and Video Translation Relate

Quick Start

1. List Supported Languages

2. Submit a Translation (Single Language)

Batch (Multiple Languages)

3. Poll for Status

Source Video Input

Speed Mode Options

Stock Voice (Enterprise)

Captions

Proofread Before Finalizing

Step 1 — Create Proofread Session

Step 2 — Poll Until `completed`

Step 3 — Download & Edit the SRT

Step 4 — Generate Final Video

Other Operations

List All Translations

Delete a Translation

When to Use Speed vs. Precision