Skip to main content
Mode: "precision" Best for: high-quality final delivery, talking-head videos, and content where accurate lip-sync is critical.

​
How Precision Mode Works

Precision mode uses avatar inference and multiple models to re-render the speaker’s mouth movements to match the translated audio—producing significantly more realistic lip-sync than Speed mode. It requires longer processing time and is recommended for polished, client-facing, or broadcast-quality output.

​
Quick Start

​
1. List Supported Languages

Before translating, fetch 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": "precision",
    "title": "High Quality Translation"
  }'

​
Batch (Multiple Languages)

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": "precision",
    "title": "Global Campaign — High Quality"
  }'
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>'
StatusMeaning
pendingQueued
runningAvatar inference in progress
completedDone — video_url is available
failedCheck failure_message
Precision mode takes longer than Speed mode — plan polling intervals accordingly (e.g. every 30–60 seconds for longer videos).

​
Source Video Input

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

​
Precision Mode Options

These parameters are particularly relevant for Precision mode:
ParameterDefaultDescription
mode"speed"Set to "precision" to enable avatar inference
speaker_numautoNumber of speakers
translate_audio_onlyfalseWhen true, skips avatar inference and only dubs audio (negates precision benefit)
enable_dynamic_durationtrueAllows output duration to vary to match natural speech pacing
disable_music_trackfalseStrips background music from output
enable_speech_enhancementfalseImproves speech audio quality
enable_captionfalseGenerates captions alongside the video
brand_voice_id—Apply a custom brand voice (requires setup)
srt—Custom subtitle file — Enterprise plan only
srt_role—"input" or "output" — which video the SRT applies to. Enterprise only
callback_url—Webhook URL notified on completion or failure
callback_id—Your own ID, echoed back in the webhook payload
Tip: Setting speaker_num is especially important in Precision mode — accurate speaker separation directly improves the quality of avatar inference per speaker.

​
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

Precision mode fully supports the proofread workflow — review and edit subtitles before committing to the full avatar inference render. This is especially valuable in Precision mode since generation takes longer and costs more.

​
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": "precision"
  }'
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

SpeedPrecision
Processing TimeFasterSlower
TranslationAdequateContext- and Gender-Aware
Lip-Sync QualityStandardHigh
Best ForFaces with little movement, quick draftsFaces with significant movement, side angles, or occlusions; final delivery videos