Video Translation - Speed - HeyGen Documentation

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 Bulk Video Translation.

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_voice_id`	—	Apply a custom brand voice (requires setup)
`callback_url`	—	Webhook URL notified on completion or failure
`callback_id`	—	Your own ID, echoed back in the webhook payload

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 Bulk Video Translation.

​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

​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