> ## 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 -  Speed

> Translate videos into 175+ languages with the HeyGen Video Translation API. Preserves the speaker's voice, applies lipsync to the target language, and exports.

**Mode:** `"speed"` (default) Best for: fast turnaround, batch jobs, and workflows where time matters more than perfect lip-sync. For higher fidelity at the cost of latency, see [Precision mode](/docs/video-translation-precision). For dozens or hundreds of videos in one job, see [Bulk Video Translation](/docs/bulk-video-translation).

## How Lip Sync and Video Translation Relate

Both APIs sit on top of **one lip sync engine** that runs in two modes — **Speed** and **Precision** — trading latency for fidelity. What differs is what each API does *around* that engine:

* **[Lip Sync API](/lipsync-speed)** — the engine on its own. You bring the video *and* your own audio; the engine redraws the mouth to match. No translation, no audio generation — dialogue replacement only.
* **[Video Translation API](/docs/video-translate)** — translation, optionally followed by the engine. It has two output modes:
  * **Audio only** (`translate_audio_only: true`) — transcribe, translate, and generate the translated audio, then stop. No lip sync. The output is just the new audio track (or the original video with swapped audio and an untouched mouth).
  * **Video (audio + visual)** — the same translation pipeline, then runs the lip sync engine so the mouth matches the translated speech.

The short version:

* **Lip Sync API** = engine only — you bring the audio.
* **Video Translation API** = translation, optionally followed by the engine. Audio-only mode skips the engine entirely; video mode adds it back.

## Quick Start

### 1. List Supported Languages

Before translating, fetch the 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": "speed",
    "title": "My Translated Video"
  }'
```

### Batch (Multiple Languages)

Translate into several languages in one request:

```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": "speed",
    "title": "Global Campaign"
  }'
```

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`   | In progress                     |
| `completed` | Done — `video_url` is available |
| `failed`    | Check `failure_message`         |

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

## Speed Mode Options

These parameters are particularly relevant for Speed mode:

| Parameter                   | Default   | Description                                                        |
| --------------------------- | --------- | ------------------------------------------------------------------ |
| `mode`                      | `"speed"` | Set to `"speed"` for faster processing                             |
| `speaker_num`               | auto      | Number of speakers                                                 |
| `translate_audio_only`      | `false`   | When `true`, only audio is translated; original video is preserved |
| `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)                        |
| `callback_url`              | —         | [Webhook](/docs/webhooks) URL notified on completion or failure    |
| `callback_id`               | —         | Your own ID, echoed back in the webhook payload                    |

## Stock Voice (Enterprise)

Use a preset "stock" voice for the translation instead of recreating the original speaker's voice.

By default, Video Translation clones the original speaker, so the translated video sounds like them. With this option enabled, the translation is spoken by a natural, preset voice that's optimized for clear pronunciation and accent in the target language. The trade-off: the result won't sound like the original speaker.

<Note>
  This is an Enterprise feature, available for selected accounts and languages and turned on by request. To use it, contact your HeyGen account team.
</Note>

Pass `stock_voice_config` in the translation request:

| Field                       | Type      | Default | Description                                                                                                              |
| --------------------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `use_stock_voice`           | boolean   | `false` | Set to `true` to use a preset stock voice instead of cloning the original speaker.                                       |
| `preferred_stock_voice_ids` | string\[] | —       | Optional. Pin specific stock voice IDs to draw from. If omitted, the target language's default stock-voice pool is used. |

```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": "speed",
    "title": "My Translated Video",
    "stock_voice_config": {
      "use_stock_voice": true
    }
  }'
```

## 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

Speed mode supports the proofread workflow — review and edit subtitles before spending credits on final generation. 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": "speed"
  }'
```

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                                    | [Precision](/docs/video-translation-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).