Video Translation - Precision

Use HeyGen Video Translation in precision mode for verbatim transcripts, terminology control, and proofread SRT inputs.

Mode: "precision" Best for: high-quality final delivery, talking-head videos, and content where accurate lip-sync is critical. For faster turnaround at lower fidelity, see Speed mode. For many videos in one job, see Bulk Video Translation.

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

Fetch 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": "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

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	Avatar inference in progress
completed	Done — video_url is available
failed	Check 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

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.

Precision Mode Options

These parameters are particularly relevant for Precision mode:

Parameter	Default	Description
mode	"speed"	Set to "precision" to enable avatar inference
speaker_num	auto	Number of speakers
translate_audio_only	false	When true, skips avatar inference and only dubs audio (negates precision benefit)
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)
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. 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": "precision"
  }'

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.