HEheygen
Video Translate

Create video translation

Changed on

Translates a video into one or more target languages. Runs asynchronously: poll with the returned video_translate_id. Get supported language codes from the languages endpoint, then set output_language or output_languages, and mode (speed or precision).

post/v2/video_translate

Request

  • Base URL
    https://api.heygen.com
  • URL
    https://api.heygen.com/v2/video_translate
  • Auth
    • API key in header x-api-key
    • or HTTP bearer

Request body

video_urlstring required

URL of the source video to translate

titlestring nullable

Title for the translation job

output_languagestring nullable

Single target language code. Mutually exclusive with output_languages.

output_languagesstring[] nullable

Multiple target language codes for batch translation. Mutually exclusive with output_language.

audio_urlstring nullable

Custom audio URL for audio dubbing

input_languagestring nullable

Source language code (auto-detected if omitted)

translate_audio_onlyboolean

Only translate audio, keep original video

speaker_numinteger nullable

Number of speakers (improves speaker separation)

mode'speed' | 'precision'

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

callback_urlstring nullable

Webhook URL for completion notifications

callback_idstring nullable

ID included in webhook payload

enable_captionboolean

Deprecated and ignored: captions are always generated; whether to display them is a download-side choice.

keep_the_same_formatboolean nullable

Preserve the source video's encoding specs (resolution, bitrate). Defaults to True for enterprise/team/pro API users with audio_url.

enable_dynamic_durationboolean

Allow dynamic duration adjustment

disable_music_trackboolean

Remove background music

enable_speech_enhancementboolean

Enhance speech quality

enable_watermarkboolean

Add watermark to output

start_timenumber nullable

Start time in seconds for partial translation

end_timenumber nullable

End time in seconds for partial translation

brand_voice_idstring nullable

Brand glossary ID for custom term translations. The 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_idstring nullable

Brand glossary ID for custom term translations (e.g. translate 'Reformer' as 'Pilates equipment', not 'political activist'). Alias for the legacy brand_voice_id field. Discover IDs via GET /v3/brand-glossaries.

srt_urlstring nullable

Custom subtitle file URL.

srt_role'input' | 'output' nullable

Which video the SRT applies to. Used with srt_url.

fps_modestring nullable

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

folder_idstring 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

Successful response

Example response

{
  "data": {
    "video_translate_id": "vt_abc123",
    "video_translate_ids": [
      "vt_abc123",
      "vt_def456"
    ]
  }
}

Changes