> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Video Translation - Precision

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

<img className="w-full h-44 object-cover rounded-xl" src="https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-6.webp?fit=max&auto=format&n=hfMXXwJzjE7vBSYZ&q=85&s=9594373cd1f749008d16bd6e93f0f76b" alt="" noZoom width="1400" height="788" data-path="images/theme/research-6.webp" />

**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](/docs/video-translate). For many videos in one job, see [Video Translation batches](/batch-video-translations).

## 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`](/reference/list-supported-translation-languages):

```bash theme={null}
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`](/reference/create-video-translation).

```bash theme={null}
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)

```bash theme={null}
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:

```json theme={null}
{
  "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}`](/reference/get-video-translation). Skip polling by passing `callback_url` — see [Webhooks](/docs/webhooks).

```bash theme={null}
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`](/reference/upload-asset) — see the [Upload Assets guide](/docs/upload-assets).

## 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. Billing is unaffected: translations are always charged on the source duration. |
| `disable_music_track` | `false` | Strips background music from output |
| `enable_speech_enhancement` | `false` | Improves speech audio quality |
| `brand_glossary_id` | — | Apply a [brand glossary](/docs/brand-glossary) so do-not-translate terms and forced translations are honored. `brand_voice_id` is the deprecated former name |
| `srt` | — | Custom subtitle file — **Enterprise plan only** |
| `srt_role` | — | `"input"` or `"output"` — which video the SRT applies to. Enterprise only |
| `callback_url` | — | [Webhook](/docs/webhooks) 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

Captions are generated in SRT and VTT. A completed [`GET /v3/video-translations/{video_translation_id}`](/reference/get-video-translation) carries them as presigned download URLs alongside the video:

```json theme={null}
{
  "data": {
    "id": "vt_abc123",
    "status": "completed",
    "video_url": "https://files.heygen.ai/...",
    "srt_caption_url": "https://files.heygen.ai/...srt",
    "vtt_caption_url": "https://files.heygen.ai/...vtt"
  }
}
```

Each field appears once `status` is `completed` and that caption file is available. A field whose URL has not been produced is left out of the response entirely rather than returned as `null`, so read `srt_caption_url` and `vtt_caption_url` with a presence check before using them. The `enable_caption` request field is retained for compatibility and no longer changes anything, since whether captions are displayed is a download-side choice.

## 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](/reference/create-proofread-session) · [Get](/reference/get-proofread-session) · [Download SRT](/reference/download-proofread-srt) · [Upload SRT](/reference/upload-proofread-srt) · [Generate Final Video](/reference/generate-video-from-proofread).

### Step 1 — Create Proofread Session

Full schema: [`POST /v3/video-translations/proofreads`](/reference/create-proofread-session).

```bash theme={null}
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}`](/reference/get-proofread-session).

```bash theme={null}
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`](/reference/download-proofread-srt); upload the revised file via [Upload Proofread SRT](/reference/upload-proofread-srt).

```bash theme={null}
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:

```bash theme={null}
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`](/reference/generate-video-from-proofread).

```bash theme={null}
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}`](/reference/get-video-translation).

## Other Operations

### List All Translations

[`GET /v3/video-translations`](/reference/list-video-translations).

```bash theme={null}
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}`](/reference/delete-video-translation).

```bash theme={null}
curl --request DELETE \
  --url 'https://api.heygen.com/v3/video-translations/<video_translation_id>' \
  --header 'x-api-key: <your-api-key>'
```

### List and Delete Proofread Sessions

[`GET /v3/video-translations/proofreads`](/reference/list-proofread-sessions) lists every proofread session in the workspace, newest first, paged with `has_more` and `next_token`. [`DELETE /v3/video-translations/proofreads/{proofread_id}`](/reference/delete-proofread-session) removes one; it needs a Creator role or higher and cannot be undone.

## When to Use Speed vs. Precision

| | [Speed](/docs/video-translate) | 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 [Video Translation batches](/batch-video-translations).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.