---
title: "Create Video Translation Batch"
method: POST
path: "/v3/video-translations/batches"
tags: ["Video Translation Batches"]
---

# Create Video Translation Batch

`POST /v3/video-translations/batches`

## Request

- Base URL: `https://api.heygen.com`
- URL: `https://api.heygen.com/v3/video-translations/batches`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Submits up to 100 translation payloads, each shaped like POST /v3/video-translations, as one batch. A payload with several `output_languages` becomes one item per language, and items run independently. Returns 202 with a `batch_id` to poll. Send an Idempotency-Key to make retries safe.

## Headers

- `Idempotency-Key` string

## Request body

- CreateVideoTranslationBatchRequest
  - `title` string, nullable: Display name for the batch, shown in the HeyGen app.
  - `callback_url` string, nullable: Webhook URL invoked once when every item in the batch reaches a terminal state.
  - `video_translations` CreateVideoTranslationRequest[], required: Video-translation payloads, identical in shape to POST /v3/video-translations. A single entry targeting multiple output_languages expands to one batch item per language; the expanded item count is capped at 100.
    - `video` union, required: Source video — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}
      - AssetUrl: Asset input via publicly accessible HTTPS URL.
        - `type` 'url', required: Input type discriminator
        - `url` string, required: Publicly accessible HTTPS URL for the asset
      - AssetId: Asset input via HeyGen asset ID from the asset upload endpoint.
        - `type` 'asset_id', required: Input type discriminator
        - `asset_id` string, required: HeyGen asset ID from the asset upload endpoint
    - `title` string, nullable: Title for the translation job
    - `output_languages` string[], required: Target language names (e.g. 'Chinese (Cantonese, Traditional)', 'Spanish (Spain)', 'English'). Use GET /v3/video-translations/languages for valid values. Use one for single translation, multiple for batch.
    - `audio` union: Custom audio for dubbing — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}
      - AssetUrl: Asset input via publicly accessible HTTPS URL.
        - `type` 'url', required: Input type discriminator
        - `url` string, required: Publicly accessible HTTPS URL for the asset
      - AssetId: Asset input via HeyGen asset ID from the asset upload endpoint.
        - `type` 'asset_id', required: Input type discriminator
        - `asset_id` string, required: HeyGen asset ID from the asset upload endpoint
    - `input_language` string, nullable: Source language code (auto-detected if omitted)
    - `translate_audio_only` boolean: Only translate audio, keep original video
    - `speaker_num` integer, nullable: Number of speakers (improves speaker separation)
    - `mode` 'speed' | 'precision'
    - `callback_url` string, nullable: Webhook URL for completion notifications
    - `callback_id` string, nullable: ID included in webhook payload
    - `enable_caption` boolean: Deprecated and ignored: captions are always generated; whether to display them is a download-side choice.
    - `keep_the_same_format` boolean, nullable: Preserve the source video's encoding specs (resolution, bitrate).
    - `enable_dynamic_duration` boolean: Allow dynamic duration adjustment
    - `disable_music_track` boolean: Remove background music
    - `enable_speech_enhancement` boolean: Enhance speech quality
    - `enable_watermark` boolean: Add watermark to output
    - `start_time` number, nullable: Start time in seconds for partial translation
    - `end_time` number, nullable: End time in seconds for partial translation
    - `brand_voice_id` string, nullable: Brand glossary ID for custom term translations. Legacy field name for `brand_glossary_id` — both are accepted and resolve to the same workspace record. Discover IDs via GET /v3/brand-glossaries.
    - `brand_glossary_id` string, nullable: Brand glossary ID for custom term translations (e.g. translate 'Reformer' as the Pilates equipment, not 'political activist'). Alias for the legacy `brand_voice_id` field. Discover IDs via GET /v3/brand-glossaries.
    - `stock_voice_config` StockVoiceConfig: Stock-voice options for a video translation request. Use a preset HeyGen voice for the translation instead of recreating the original speaker's voice. Enterprise feature, available for selected accounts and languages by request. See the ``stock_voice_config`` request field for usage.
      - `use_stock_voice` boolean: 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.
    - `srt` union: Custom subtitle file — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}.
      - AssetUrl: Asset input via publicly accessible HTTPS URL.
        - `type` 'url', required: Input type discriminator
        - `url` string, required: Publicly accessible HTTPS URL for the asset
      - AssetId: Asset input via HeyGen asset ID from the asset upload endpoint.
        - `type` 'asset_id', required: Input type discriminator
        - `asset_id` string, required: HeyGen asset ID from the asset upload endpoint
    - `srt_role` 'input' | 'output', nullable: Which video the subtitle applies to: 'input' (source) or 'output' (translated).
    - `fps_mode` 'vfr' | 'cfr' | 'passthrough', nullable: Frame rate mode for the output video. 'vfr' = variable frame rate, 'cfr' = constant frame rate, 'passthrough' = match the source. Only takes effect when a custom 'audio' track is provided.
    - `folder_id` string, nullable: Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to. Assets library folders are accepted, but the HeyGen app files only assets in them, so a result placed there may not appear in the Assets library view. An unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created.

## Response `202`

Accepted — submission acknowledged; poll for completion.

- object
  - `data` CreateVideoTranslationBatchResponse
    - `batch_id` string, required: Identifier of the created batch. Poll GET /v3/video-translations/batches/{batch_id} for progress.

## Other responses

- `400`: Invalid request parameters
- `401`: Authentication failed
- `409`: A prior request with this Idempotency-Key is still in progress. Wait for the original request to complete, then retry.
- `429`: Rate limit exceeded

## Changes

- **2026-11-03** `7dfa5e59b4f5`: 13 info
  - request property `video_translations/items/brand_voice_id` deprecated
  - request property `video_translations/items/enable_caption` deprecated
  - added `asset_id, url` discriminator mapping keys to the `video_translations/items/audio/anyOf[subschema #1]/` request property
  - added `asset_id, url` discriminator mapping keys to the `video_translations/items/srt/anyOf[subschema #1]/` request property
  - …9 more

[Operation history](https://skmtc.dev/heygen/apis/heygen-external-api/changes/v3/video-translations/batches/post.md)

---

[API](https://skmtc.dev/heygen/apis/heygen-external-api.md) - [All operations](https://skmtc.dev/heygen/apis/heygen-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/heygen/apis/heygen-external-api/revisions/7dfa5e59b4f5?raw)