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>"
}
'

Response Codes

• 200: Success
• 400: Bad request
• 401: Unauthorized
• 429: Too many requests

{
  "data": {
    "video_translation_ids": [\
      "<string>"\
    ]
  }
}

Authorizations

• ApiKeyAuthBearerAuth

x-api-key

• Type: string
• Location: header
• Required: Yes

HeyGen API key. Obtain from your HeyGen dashboard.

Body

application/json
Request body for POST /v3/video-translations.

• video

  • AssetUrl: object required
    • AssetUrl
    • AssetId

• output_languages

  • string[] required
    • Target language names (e.g. 'Chinese (Cantonese, Traditional)', 'Spanish (Spain)', 'English').
    • Minimum array length: 1

• title

  • string | null
    • Title for the translation job

• audio

  • AssetUrl: object required
    • AssetUrl
    • AssetId

• 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
    • Default: speed
    • Translation quality mode: 'speed' (faster) or 'precision' (higher quality)

• 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 required
    • AssetUrl
    • AssetId

• srt_role

  • enum | null
    • Which video the subtitle applies to: 'input' (source) or 'output' (translated)

• fps_mode

  • string | null
    • Frame rate mode: 'vfr', 'cfr', or 'passthrough'.

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