Skip to main content
POST
/
v3
/
video-translations
Create Video Translation
curl --request POST \
  --url https://api.heygen.com/v3/video-translations \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "video": {
    "type": "<string>",
    "url": "<string>"
  },
  "output_languages": [
    "<string>"
  ],
  "title": "<string>",
  "audio": {
    "type": "<string>",
    "url": "<string>"
  },
  "input_language": "<string>",
  "translate_audio_only": false,
  "speaker_num": 123,
  "mode": "speed",
  "callback_url": "<string>",
  "callback_id": "<string>",
  "enable_caption": false,
  "keep_the_same_format": true,
  "enable_dynamic_duration": true,
  "disable_music_track": false,
  "enable_speech_enhancement": false,
  "enable_watermark": false,
  "start_time": 123,
  "end_time": 123,
  "brand_voice_id": "<string>",
  "stock_voice_config": {
    "use_stock_voice": false,
    "preferred_stock_voice_ids": [
      "<string>"
    ]
  },
  "srt": {
    "type": "<string>",
    "url": "<string>"
  },
  "folder_id": "<string>"
}
'
{
  "data": {
    "video_translation_ids": [
      "<string>"
    ]
  }
}

Documentation Index

Fetch the complete documentation index at: https://developers.heygen.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
x-api-key
string
header
required

HeyGen API key. Obtain from your HeyGen dashboard.

Headers

​
Idempotency-Key
string

Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent.

Required string length: 1 - 255
Pattern: ^[A-Za-z0-9_\-:.]{1,255}$

Body

application/json

Request body for POST /v3/video-translations.

​
video
AssetUrl · object
required

Asset input via publicly accessible HTTPS URL.

​
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.

Minimum array length: 1
​
title
string | null

Title for the translation job

​
audio
AssetUrl · object

Asset input via publicly accessible HTTPS URL.

​
input_language
string | null

Source language code (auto-detected if omitted)

​
translate_audio_only
boolean
default:false

Only translate audio, keep original video

​
speaker_num
integer | null

Number of speakers (improves speaker separation)

​
mode
enum<string>
default:speed

Translation quality mode: 'speed' (faster) or 'precision' (higher quality, uses avatar inference)

Available options:
speed,
precision
​
callback_url
string | null

Webhook URL for completion notifications

​
callback_id
string | null

ID included in webhook payload

​
enable_caption
boolean
default:false

Generate captions for translated video

​
keep_the_same_format
boolean | null

Preserve the source video's encoding specs (resolution, bitrate).

​
enable_dynamic_duration
boolean
default:true

Allow dynamic duration adjustment

​
disable_music_track
boolean
default:false

Remove background music

​
enable_speech_enhancement
boolean
default:false

Enhance speech quality

​
enable_watermark
boolean
default:false

Add watermark to output

​
start_time
number | null

Start time in seconds for partial translation

​
end_time
number | null

End time in seconds for partial translation

​
brand_voice_id
string | null

Custom brand voice ID. Requires brand voice setup.

​
stock_voice_config
StockVoiceConfig · object

Opt into Stock TTS instead of Voice Clone. Set use_stock_voice=true to route the request to a stock voice; optionally pin specific voices via preferred_stock_voice_ids. Gated by per-space and per-locale Nacos allowlists.

​
srt
AssetUrl · object

Asset input via publicly accessible HTTPS URL.

​
srt_role
enum<string> | null

Which video the subtitle applies to: 'input' (source) or 'output' (translated). Enterprise plan only.

Available options:
input,
output
​
fps_mode
enum<string> | null

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.

Available options:
vfr,
cfr,
passthrough
​
folder_id
string | null

Project/folder ID to organize translation into

Response

Successful response

​
data
VideoTranslationCreateResponse · object

Response for POST /v3/video-translations.