Skip to main content

​
List Supported Languages

Before translating a video, retrieve the list of supported target languages: 
curl --request GET \
  --url 'https://api.heygen.com/v3/video-translations/languages' \
  --header 'accept: application/json' \
  --header 'x-api-key: <your-api-key>'
The response returns an array of language codes you can use as output_languages values in translation requests.

​
Translate a Video

Submit a translation request with your source video and target language(s). The video is translated asynchronously — the response returns ID(s) you use to poll for status.

​
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"],
    "title": "My Translated Video"
  }'

​
Multiple Languages (Batch)

Translate the same source video into multiple languages in a single request by passing additional language codes in the array: 
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"],
    "title": "Global Campaign"
  }'
The response returns one video_translation_id per target language: 
{
  "data": {
    "video_translation_ids": [
      "tr_abc123-en",
      "tr_abc123-es",
      "tr_abc123-fr"
    ]
  }
}

​
Providing the Source Video

The video field accepts two input types:
  • URL — a publicly accessible HTTPS link to the video file: 
    { "type": "url", "url": "https://example.com/video.mp4" }
  • Asset ID — a HeyGen asset ID from POST /v3/assets: 
    { "type": "asset_id", "asset_id": "<asset_id>" }
The URL must be publicly accessible — if you paste it into an incognito browser window, the video should play without any login.

​
Translation Options

ParameterDefaultDescription
mode"speed""speed" for faster results, "precision" for higher quality (uses avatar inference).
translate_audio_onlyfalseWhen true, only the audio is translated — the original video is preserved.
speaker_numautoNumber of speakers in the video. Setting this improves speaker separation accuracy.
enable_captionfalseGenerate captions for the translated video. Required to later retrieve caption files.
enable_dynamic_durationtrueAllow the translated video duration to differ from the source to match natural speech pacing.
disable_music_trackfalseRemove background music from the output.
enable_speech_enhancementfalseEnhance speech quality in the output.
brand_voice_id—Apply a custom brand voice. Requires prior brand voice setup.
audio—Custom audio for dubbing, provided as {"type": "url", "url": "..."} or {"type": "asset_id", "asset_id": "..."}.
srt—Custom subtitle file (same typed object format). Enterprise plan only.
srt_role—"input" or "output" — which video the SRT applies to. Enterprise plan only.
callback_url—Webhook URL to receive a notification when the translation completes or fails.
callback_id—Your own identifier, echoed back in the webhook payload.

​
Check Translation Status

Poll the translation status using the ID returned from the create request: 
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>'
Possible status values:
StatusDescription
pendingTranslation is queued.
runningTranslation is in progress.
completedDone. The response includes video_url (and optionally audio_url).
failedFailed. Check failure_message for details.
The presigned URL parameters are regenerated each time you call the status endpoint, so you can always get a fresh link.

​
List Translations

Retrieve a paginated list of all your video translations: 
curl --request GET \
  --url 'https://api.heygen.com/v3/video-translations?limit=10' \
  --header 'accept: application/json' \
  --header 'x-api-key: <your-api-key>'
The response includes has_more and next_token for cursor-based pagination. Pass token=<next_token> to fetch the next page.

​
Get Translation Captions

If you created the translation with enable_caption: true, download the caption file once the translation is complete: 
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 and vtt.

​
Proofread Before Translating

The proofread workflow lets you review and edit subtitles before generating the final translated video. This is useful for ensuring translation accuracy before spending credits on video generation.

​
1. Create a Proofread Session

curl --request POST \
  --url 'https://api.heygen.com/v3/video-translations/proofreads' \
  --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"],
    "title": "Review Before Publishing"
  }'
This returns proofread_ids — one per target language.

​
2. Poll Proofread Status

curl --request GET \
  --url 'https://api.heygen.com/v3/video-translations/proofreads/<proofread_id>' \
  --header 'accept: application/json' \
  --header 'x-api-key: <your-api-key>'
Wait until the status is completed.

​
3. Download and Edit the SRT

curl --request GET \
  --url 'https://api.heygen.com/v3/video-translations/proofreads/<proofread_id>/srt' \
  --header 'accept: application/json' \
  --header 'x-api-key: <your-api-key>'
This returns srt_url (the editable translated SRT) and optionally original_srt_url. Download the file, make your edits, then upload the revised version: 
curl --request PUT \
  --url 'https://api.heygen.com/v3/video-translations/proofreads/<proofread_id>/srt' \
  --header 'accept: application/json' \
  --header 'x-api-key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "srt": {
      "type": "url",
      "url": "<your_edited_srt_url>"
    }
  }'

​
4. Generate the Final Video

curl --request POST \
  --url 'https://api.heygen.com/v3/video-translations/proofreads/<proofread_id>/generate' \
  --header 'accept: application/json' \
  --header 'x-api-key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "captions": true
  }'
This returns a video_translation_id that you poll via GET /v3/video-translations/<id> as described above.

​
Delete a Translation

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