HEheygen
Video Translate

Create Video Translation

Changed on

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.

post/v3/video-translations

Request

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

Headers

Idempotency-Keystring

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.

Request body

titlestring nullable

Title for the translation job

output_languagesstring[] 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.

input_languagestring nullable

Source language name, e.g. 'English' (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'
callback_urlstring nullable

Webhook URL for completion notifications

callback_idstring nullable

ID included in webhook payload

output_uploadsobject nullable

Upload each translated video's files straight into your own storage, keyed by a language from output_languages. Give a presigned PUT URL per file, for Amazon S3, Google Cloud Storage or Azure Blob Storage; HeyGen uploads each file when that language finishes. Languages without an entry are not uploaded. Not available with audio input or in batches. Available to enabled workspaces.

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

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. 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 the Pilates equipment, not 'political activist'). Alias for the legacy brand_voice_id field. Discover IDs via GET /v3/brand-glossaries.

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

Changes

  • a5c5262935e5Revision changes
    • info

      added the new optional request property

  • 7dfa5e59b4f5Revision changes
    • info

      request property deprecated

    • info

      request property deprecated

    • info

      added asset_id url discriminator mapping keys to the / request property

    • info

      added asset_id url discriminator mapping keys to the / request property

    • info

      added asset_id url discriminator mapping keys to the request property

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status