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

# Create Video Translation

`POST /v3/video-translations`

Translates a video into one or more target languages with voice cloning and lip-sync. Returns one video_translation_id per language. Use mode: 'speed' (default) for fast turnaround or 'precision' for higher lip-sync quality.

## Headers

- `Idempotency-Key` string

## Request body

- CreateVideoTranslationRequest — Request body for POST /v3/video-translations.
  - `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 — Generate captions for translated video
  - `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 — Project/folder ID to organize translation into

## Response `200`

Successful response

- object
  - `data` VideoTranslationCreateResponse — Response for POST /v3/video-translations.
    - `video_translation_ids` string[], required — Video translation IDs, one per target language

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

---

[API](https://skmtc.net/heygen/apis/heygen-external-api.md) · [All operations](https://skmtc.net/heygen/apis/heygen-external-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/heygen/heygen-external-api/versions/e2e54726e210/schema)