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

> Submit up to 100 video translation requests in a single call. Fan one source video out to many languages, then poll one batch id for per-item progress.

![](https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-4.webp?fit=max\&auto=format\&n=hfMXXwJzjE7vBSYZ\&q=85\&s=ed7eea7e860c769f9b1b12804a27315a)

## Overview

Translation batches let you submit many translations in one request instead of calling [`POST /v3/video-translations`](https://heygen-1fa696a7.mintlify.site/reference/create-video-translation) once per job. Each item is a standard translation payload, the exact shape that endpoint accepts, so anything you can translate on its own can be batched, in either [Speed](https://heygen-1fa696a7.mintlify.site/docs/video-translate.md) or [Precision](https://heygen-1fa696a7.mintlify.site/docs/video-translation-precision.md) mode. Batch mechanics (`202 Accepted`, `title`, `callback_url`, `Idempotency-Key`, the batch read model and pagination) match [video batches](https://heygen-1fa696a7.mintlify.site/batch-videos.md).

> [!NOTE]
>
> A batch holds up to **100** items. A single payload targeting multiple `output_languages` expands to **one batch item per language**, and the expanded count is what the 100-item cap applies to. Each item is created and processed independently, so one bad source does not fail the rest.

## Create a Batch

[`POST /v3/video-translations/batches`](https://heygen-1fa696a7.mintlify.site/reference/create-video-translation-batch) takes the payloads in `video_translations`. One source video fanned out to three languages creates three batch items:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/video-translations/batches" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Q3 keynote, localized cuts",
    "callback_url": "https://example.com/hooks/heygen",
    "video_translations": [
      {
        "video": { "type": "url", "url": "https://example.com/keynote.mp4" },
        "title": "Q3 keynote",
        "output_languages": ["Spanish (Spain)", "French", "Japanese"],
        "mode": "speed"
      }
    ]
  }'
```

Each entry takes the full set of translation options: `video` (as a `url` or `asset_id`), `output_languages` (use [`GET /v3/video-translations/languages`](https://heygen-1fa696a7.mintlify.site/reference/list-supported-translation-languages) for valid values), `mode` (`speed` or `precision`), plus captions, [brand glossary](https://heygen-1fa696a7.mintlify.site/docs/brand-glossary.md), stock voice, partial-range, and format controls.

## Get a Batch

Poll [`GET /v3/video-translations/batches/{batch_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-video-translation-batch). The response shape matches the [video batch](https://heygen-1fa696a7.mintlify.site/batch-videos.md#response-fields).

> [!NOTE]
>
> The batch read model is shared across the batch APIs, so the per-item id field is named `video_id`. For translation batches it holds the **video translation id**. Use it with [`GET /v3/video-translations/{video_translation_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-video-translation) for the full record and download URL.

## Bulk Statuses

[`GET /v3/video-translations/statuses`](https://heygen-1fa696a7.mintlify.site/reference/bulk-video-translation-statuses) checks up to 100 translations in one request, across batches or for jobs created individually. Pass comma-separated `video_translation_ids`, or `batch_ids` (each expands to its member translations). Statuses are `queued`, `processing`, `completed`, or `failed`, plus `not_found` for unknown or unowned ids.

## Tracking completion

Besides the batch `callback_url` and polling, you can subscribe to `video_translate.success` / `video_translate.fail` [webhook events](https://heygen-1fa696a7.mintlify.site/docs/webhook-events.md) for per-item notifications. Items surface their translation id as soon as the job is created, so you can start fetching finished translations while the rest of the batch is still processing.


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