> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.app/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.

**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 [Bulk Video Translation](/docs/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`](/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                       |
| `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](/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

To enable captions, set `enable_caption: true` in the translation request. Once completed, download them:

```bash theme={null}
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](/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>'
```

## 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 [Bulk Video Translation](/docs/bulk-video-translation).