Video Translation - Speed

Mode: "speed" (default) Best for: fast turnaround, batch jobs, and workflows where time matters more than perfect lip-sync.

Quick Start

1. List Supported Languages

Before translating, fetch the available target language codes:

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)

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

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).

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.

Step 1 — Create Proofread Session

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

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

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

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/<id>.

Other Operations

List All 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

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