Create video translation

Translate a video into one or more target languages. The translation runs asynchronously — the response contains an id (or ids for batch) which can be used to poll status.

Use GET /v3/video-translations/languages to discover supported language codes.

POST /v3/video-translations

Create video translation

cURL

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>",
  "srt": {
    "type": "<string>",
    "url": "<string>"
  },
  "srt_role": "input",
  "fps_mode": "<string>",
  "folder_id": "<string>"
}
'

200

{}

Authorizations

ApiKeyAuthBearerAuth

x-api-key · string · header · required

HeyGen API key. Obtain from your HeyGen dashboard.

Body

application/json

Request body for POST /v3/video-translations.

video · AssetUrl · object · required

Asset input via publicly accessible HTTPS URL.

AssetUrl

AssetId

Show child attributes

output_languages · string[] · required

Target language codes. 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.

AssetUrl

AssetId

Show child attributes

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.

srt · AssetUrl · object

Asset input via publicly accessible HTTPS URL.

AssetUrl

AssetId

Show child attributes

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 · string | null

Frame rate mode: 'vfr', 'cfr', or 'passthrough'. Only valid with audio.

folder_id · string | null

Project/folder ID to organize translation into

Response

200

application/json

Successful response

data · VideoTranslationCreateResponse · object

Response for POST /v3/video-translations.

Show child attributes