HeyGen

App · 22 actions

Make AI avatar videos with HeyGen: have an avatar or a photo speak your script, generate videos from a prompt or a template, translate videos with lip-sync, and turn text into speech. Start workflows when a video or translation is ready.

Actions

ActionWhat it does
Create avatar videoStart a video of an avatar speaking your script (or lip-syncing audio).
Create talking photo videoStart a video of the person in a photo speaking your script (or lip-syncing audio), with no avatar to set up.
Create video from promptDescribe a video and HeyGen's Video Agent writes the script, picks the avatar and voice (unless you do) and renders it.
Create video from templateStart a video from a template, filling in its values by name.
Delete videoDelete a video and its files from HeyGen.
Generate speechTurn text into speech with a HeyGen voice and get a link to the audio file.
Get accountGet the HeyGen account the API key belongs to and how much it has left to spend: its API balance in dollars or its credits.
Get prompt videoSee how far a prompt video has got.
Get templateGet a template and the values it lets you fill in, with their names, kinds and current values.
Get translationGet a translation's status and, once it's ready, its video, audio and caption links.
Get videoGet a video's status and, once it's ready, its download link, thumbnail and captions.
List avatar looksList avatar looks (outfits and styles).
List avatarsList avatars (the characters), your own and HeyGen's stock ones.
List templatesList the templates you can make videos from: those built in HeyGen's editor with values to fill in.
List translation languagesList the languages HeyGen can translate a video into.
List translationsList the account's video translations with their status and links.
List videosList the account's videos with their status and download links, optionally only those whose title contains some text.
List voicesList voices from HeyGen's library or your own, by language and gender, with a sample of each.
Translate videoTranslate a video into one or more languages in the speaker's own voice, with lip-sync.
Upload fileUpload an image, video, audio file or PDF (up to 32 MB) to HeyGen and get a public link the photo, video and translation steps take.
Wait for translationWait until a translation is ready, then return its links.
Wait for videoWait until a video is ready, then return its download link.

Create avatar video

Start a video of an avatar speaking your script (or lip-syncing audio). It is paid for from your HeyGen balance and takes a few minutes: follow with 'Wait for video' to get the file.

Inputs

Avataravatar_idtextRequired
The avatar look to appear in the video. Pick one, or give a look id from 'List avatar looks'.
Scriptscripttext
What to say, up to 5,000 characters. Leave empty only when giving an audio link to lip-sync instead.
Voicevoice_idtext
The voice that speaks the script. Leave empty to use the avatar's own voice.
Audio linkaudio_urltext
Instead of a script: a public link to an MP3 or WAV file (up to 10 minutes) to lip-sync.
Titletitletext
The video's title in HeyGen.
Shapeaspect_ratiotext
The video's shape. Defaults to 16:9 landscape.One of: 16:9 (16:9 landscape (default)), 9:16 (9:16 portrait, for Reels, Shorts and TikTok), 1:1 (1:1 square), 4:5 (4:5 portrait, for feeds), 5:4 (5:4 landscape), auto (Match the avatar or photo).
Resolutionresolutiontext
The video's resolution. Higher costs more.One of: 720p, 1080p (1080p (full HD)), 4k (4K (Avatar III digital twins and studio avatars only)).
Background colourbackground_colortext
A solid background as a hex colour, such as #FFFFFF for white. Leave empty to keep the avatar's own background.
Burn in captionscaptionstrue/false
Yes shows captions in the video. A caption file comes back either way.
Voice speedvoice_speednumber
How fast the script is spoken, 0.5 to 1.5. Defaults to 1.From 0.5 to 1.5.
Engineenginetext
Which HeyGen model animates the avatar. Defaults to Avatar IV; 'List avatar looks' shows which a look supports.One of: avatar_iv (Avatar IV (default)), avatar_v (Avatar V, the most natural (supported looks only)), avatar_iii (Avatar III).

Outputs

statustext
Where it is up to, such as pending
video_idtext
The new video's id, for 'Wait for video' or 'Get video'
Example output
{
  "status": "pending",
  "video_id": "8f3c2b1a9d4e4c7b"
}

Create talking photo video

Start a video of the person in a photo speaking your script (or lip-syncing audio), with no avatar to set up. Paid for from your HeyGen balance; follow with 'Wait for video'.

Inputs

Photo linkimage_urltextRequired
A public link to a JPG or PNG of one person facing the camera. 'Upload file' gives one for a file you have.
Scriptscripttext
What to say, up to 5,000 characters. Leave empty only when giving an audio link to lip-sync instead.
Voicevoice_idtext
The voice that speaks the script. Needed with a script.
Audio linkaudio_urltext
Instead of a script: a public link to an MP3 or WAV file (up to 10 minutes) to lip-sync.
Titletitletext
The video's title in HeyGen.
Shapeaspect_ratiotext
The video's shape. Defaults to 16:9 landscape.One of: 16:9 (16:9 landscape (default)), 9:16 (9:16 portrait, for Reels, Shorts and TikTok), 1:1 (1:1 square), 4:5 (4:5 portrait, for feeds), 5:4 (5:4 landscape), auto (Match the avatar or photo).
Resolutionresolutiontext
The video's resolution. Higher costs more.One of: 720p, 1080p (1080p (full HD)), 4k (4K (Avatar III digital twins and studio avatars only)).
Burn in captionscaptionstrue/false
Yes shows captions in the video. A caption file comes back either way.
Voice speedvoice_speednumber
How fast the script is spoken, 0.5 to 1.5. Defaults to 1.From 0.5 to 1.5.
Expressivenessexpressivenesstext
How animated the face is. Defaults to low.One of: low (Low (default)), medium, high.
Motionmotion_prompttext
How the person should move, such as 'nods and smiles'.

Outputs

statustext
Where it is up to, such as pending
video_idtext
The new video's id, for 'Wait for video' or 'Get video'
Example output
{
  "status": "pending",
  "video_id": "8f3c2b1a9d4e4c7b"
}

Create video from prompt

Describe a video and HeyGen's Video Agent writes the script, picks the avatar and voice (unless you do) and renders it. Paid for from your HeyGen balance; follow with 'Get prompt video'.

Inputs

PromptprompttextRequired
What the video should be, up to 10,000 characters: its topic, length, tone and any lines to say.
Avataravatar_idtext
The avatar look to use. Leave empty to let HeyGen pick.
Voicevoice_idtext
The voice to narrate with. Leave empty to let HeyGen pick.
Stylestyle_idtext
A visual style. Leave empty to let HeyGen pick.
Orientationorientationtext
Landscape or portrait. Chosen from the prompt if empty.One of: landscape, portrait.

Outputs

session_idtext
The prompt video's id, for 'Get prompt video'
statustext
Where it is up to, such as thinking
video_idtext
The video's id if rendering has started; empty until then
Example output
{
  "session_id": "sess_abc123",
  "status": "generating",
  "video_id": ""
}

Create video from template

Start a video from a template, filling in its values by name. Paid for from your HeyGen balance; follow with 'Wait for video'.

Inputs

Templatetemplate_idtextRequired
The template. Pick one, or give its id.
Valuesvaluesobject
Each value's name with what to put in it, such as {"first_name": "Sam"}. Text takes words, an image, video or audio a public link, a character an avatar look id, a voice a voice id. Every text value must be filled in; 'Get template' lists them.
Titletitletext
The video's title in HeyGen.
Burn in captionscaptionstrue/false
Yes shows captions in the video. A caption file comes back either way.

Outputs

statustext
Where it is up to, such as pending
video_idtext
The new video's id, for 'Wait for video' or 'Get video'
Example output
{
  "status": "pending",
  "video_id": "8f3c2b1a9d4e4c7b"
}

Delete video

Delete a video and its files from HeyGen. There is no undo.

Inputs

Video IDvideo_idtextRequired
The video's id, from a create step or 'List videos'.

Outputs

deletedtrue/false
Always true once deleted
video_idtext
The video deleted
Example output
{
  "deleted": true,
  "video_id": "8f3c2b1a9d4e4c7b"
}

Generate speech

Turn text into speech with a HeyGen voice and get a link to the audio file.

Inputs

TexttexttextRequired
What to say, up to 5,000 characters.
Voicevoice_idtextRequired
The voice to speak with.
Speedspeednumber
How fast to speak, 0.5 to 2. Defaults to 1.From 0.5 to 2.
Language codelanguagetext
The text's language as a code such as en, es or pt. Detected from the text if empty.

Outputs

audio_urltext
Link to the audio file
durationnumber
Length in seconds
enginetext
The speech engine HeyGen used
Example output
{
  "audio_url": "https://files.heygen.ai/speech/7c1e2d3f.mp3",
  "duration": 2.1,
  "engine": "starfish"
}

Get account

Get the HeyGen account the API key belongs to and how much it has left to spend: its API balance in dollars or its credits.

Inputs

None.

Outputs

balance_unittext
USD or credits
plantext
The plan, for an account paying with plan credits; empty otherwise
remaining_balancenumber
What the account has left: dollars for an API balance, or credits
userobject
The HeyGen account the API key belongs to
Example output
{
  "balance_unit": "USD",
  "plan": "",
  "remaining_balance": 42.5,
  "user": {
    "billing_type": "wallet",
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "username": "jane_doe"
  }
}

Get prompt video

See how far a prompt video has got. Once HeyGen starts rendering it, its video id is here for 'Wait for video'.

Inputs

Prompt video IDsession_idtextRequired
The id 'Create video from prompt' returned.

Outputs

sessionobject
The prompt video's progress
session_idtext
The prompt video's id
statustext
thinking, waiting_for_input, reviewing, generating, completed or failed
video_idtext
The video's id once rendering has started; empty until then
Example output
{
  "session": {
    "created_at": 1761300000,
    "error": null,
    "progress": 40,
    "session_id": "sess_abc123",
    "status": "generating",
    "title": "New dashboard update",
    "video_id": "8f3c2b1a9d4e4c7b"
  },
  "session_id": "sess_abc123",
  "status": "generating",
  "video_id": "8f3c2b1a9d4e4c7b"
}

Get template

Get a template and the values it lets you fill in, with their names, kinds and current values.

Inputs

Templatetemplate_idtextRequired
The template. Pick one, or give its id.

Outputs

templateobject
A template
variable_nameslist
Just the values' names
variableslist
The values you can fill in
Example output
{
  "template": {
    "aspect_ratio": "16:9",
    "created_at": 1761200000,
    "id": "3e9d1c7b5a2f4e8d",
    "name": "Customer welcome",
    "thumbnail_url": "https://files.heygen.ai/template/3e9d1c7b5a2f4e8d.jpg",
    "updated_at": 1761250000
  },
  "variable_names": [
    "first_name",
    "logo"
  ],
  "variables": [
    {
      "current_value": "Sam",
      "name": "first_name",
      "type": "text"
    },
    {
      "current_value": "https://files.heygen.ai/asset/logo.png",
      "name": "logo",
      "type": "image"
    }
  ]
}

Get translation

Get a translation's status and, once it's ready, its video, audio and caption links.

Inputs

Translation IDvideo_translation_idtextRequired
The translation's id, from 'Translate video' or 'List translations'.

Outputs

readytrue/false
True once the translation is finished
statustext
pending, running, completed or failed
translationobject
The translation
video_translation_idtext
The translation's id
video_urltext
Download link for the translated video, empty until it is ready
Example output
{
  "ready": true,
  "status": "completed",
  "translation": {
    "audio_url": "https://files.heygen.ai/translate/5b2a7c9e1f3d4a6b.mp3",
    "created_at": 1761300300,
    "duration": 12.4,
    "failure_code": null,
    "failure_message": null,
    "id": "5b2a7c9e1f3d4a6b",
    "input_language": "en",
    "output_language": "Spanish (Spain)",
    "srt_caption_url": "https://files.heygen.ai/translate/5b2a7c9e1f3d4a6b.srt",
    "status": "completed",
    "title": "Welcome, Sam (Spanish)",
    "translate_audio_only": false,
    "video_url": "https://files.heygen.ai/translate/5b2a7c9e1f3d4a6b.mp4",
    "vtt_caption_url": "https://files.heygen.ai/translate/5b2a7c9e1f3d4a6b.vtt"
  },
  "video_translation_id": "5b2a7c9e1f3d4a6b",
  "video_url": "https://files.heygen.ai/translate/5b2a7c9e1f3d4a6b.mp4"
}

Get video

Get a video's status and, once it's ready, its download link, thumbnail and captions.

Inputs

Video IDvideo_idtextRequired
The video's id, from a create step or 'List videos'.

Outputs

readytrue/false
True once the video is finished
statustext
pending, processing, completed or failed
videoobject
The video
video_idtext
The video's id
video_urltext
Download link for the finished video, empty until it is ready. It expires after a while.
Example output
{
  "ready": true,
  "status": "completed",
  "video": {
    "captioned_video_url": null,
    "completed_at": 1761300180,
    "created_at": 1761300000,
    "duration": 12.4,
    "failure_code": null,
    "failure_message": null,
    "folder_id": null,
    "gif_url": null,
    "id": "8f3c2b1a9d4e4c7b",
    "output_language": null,
    "status": "completed",
    "subtitle_url": "https://files.heygen.ai/caption/8f3c2b1a9d4e4c7b.srt",
    "thumbnail_url": "https://files.heygen.ai/thumbnail/8f3c2b1a9d4e4c7b.jpg",
    "title": "Welcome, Sam",
    "video_page_url": "https://app.heygen.com/videos/8f3c2b1a9d4e4c7b",
    "video_url": "https://files.heygen.ai/video/8f3c2b1a9d4e4c7b.mp4"
  },
  "video_id": "8f3c2b1a9d4e4c7b",
  "video_url": "https://files.heygen.ai/video/8f3c2b1a9d4e4c7b.mp4"
}

List avatar looks

List avatar looks (outfits and styles). A look's id is what 'Create avatar video' takes as its Avatar.

Inputs

Avataravatar_group_idtext
Only the looks of this avatar.
Kindavatar_typetext
Only looks of this kind.One of: studio_avatar (Studio avatar), digital_twin (Digital twin), photo_avatar (Photo avatar).
Whoseownershiptext
Only your own avatars, or only HeyGen's stock ones. Both if empty.One of: private (My own avatars), public (HeyGen's stock avatars).
Page sizelimitnumber
How many to return, 1 to 50. HeyGen's default is 20.From 1 to 50.
Next pagepage_tokentext
The 'next_page_token' an earlier run of this step gave, to get the page after it.

Outputs

countnumber
How many on this page
has_moretrue/false
True when there are more after this page
lookslist
The avatar looks
next_page_tokentext
Give this as the Next page field to get the next page; empty on the last one
Example output
{
  "count": 1,
  "has_more": false,
  "looks": [
    {
      "avatar_type": "studio_avatar",
      "default_voice_id": "f38a635bee7a4d1f9b0a654a31d050d2",
      "gender": "female",
      "group_id": "a1b2c3d4e5f6",
      "id": "Abigail_expressive_2024112501",
      "name": "Abigail (Upper Body)",
      "preferred_orientation": "landscape",
      "preview_image_url": "https://files.heygen.ai/avatar/abigail.webp",
      "preview_video_url": "https://files.heygen.ai/avatar/abigail.mp4",
      "status": "completed",
      "supported_api_engines": [
        "avatar_iv",
        "avatar_iii"
      ],
      "tags": [
        "professional"
      ]
    }
  ],
  "next_page_token": ""
}

List avatars

List avatars (the characters), your own and HeyGen's stock ones. Each has one or more looks: use 'List avatar looks' for the ids a video takes.

Inputs

Whoseownershiptext
Only your own avatars, or only HeyGen's stock ones. Both if empty.One of: private (My own avatars), public (HeyGen's stock avatars).
Page sizelimitnumber
How many to return, 1 to 50. HeyGen's default is 20.From 1 to 50.
Next pagepage_tokentext
The 'next_page_token' an earlier run of this step gave, to get the page after it.

Outputs

avatarslist
The avatars
countnumber
How many on this page
has_moretrue/false
True when there are more after this page
next_page_tokentext
Give this as the Next page field to get the next page; empty on the last one
Example output
{
  "avatars": [
    {
      "created_at": 1730000000,
      "default_voice_id": "f38a635bee7a4d1f9b0a654a31d050d2",
      "gender": "female",
      "id": "a1b2c3d4e5f6",
      "looks_count": 3,
      "name": "Abigail",
      "preview_image_url": "https://files.heygen.ai/avatar/abigail.webp",
      "preview_video_url": "https://files.heygen.ai/avatar/abigail.mp4",
      "status": "completed"
    }
  ],
  "count": 1,
  "has_more": false,
  "next_page_token": ""
}

List templates

List the templates you can make videos from: those built in HeyGen's editor with values to fill in.

Inputs

Page sizelimitnumber
How many to return, 1 to 100.From 1 to 100.
Next pagepage_tokentext
The 'next_page_token' an earlier run of this step gave, to get the page after it.

Outputs

countnumber
How many on this page
has_moretrue/false
True when there are more after this page
next_page_tokentext
Give this as the Next page field to get the next page; empty on the last one
templateslist
The templates
Example output
{
  "count": 1,
  "has_more": false,
  "next_page_token": "",
  "templates": [
    {
      "aspect_ratio": "16:9",
      "created_at": 1761200000,
      "id": "3e9d1c7b5a2f4e8d",
      "name": "Customer welcome",
      "thumbnail_url": "https://files.heygen.ai/template/3e9d1c7b5a2f4e8d.jpg",
      "updated_at": 1761250000
    }
  ]
}

List translation languages

List the languages HeyGen can translate a video into.

Inputs

None.

Outputs

countnumber
How many
languageslist
The language names 'Translate video' takes
Example output
{
  "count": 3,
  "languages": [
    "English",
    "Spanish (Spain)",
    "French (France)"
  ]
}

List translations

List the account's video translations with their status and links.

Inputs

Page sizelimitnumber
How many to return, 1 to 100.From 1 to 100.
Next pagepage_tokentext
The 'next_page_token' an earlier run of this step gave, to get the page after it.

Outputs

countnumber
How many on this page
has_moretrue/false
True when there are more after this page
next_page_tokentext
Give this as the Next page field to get the next page; empty on the last one
translationslist
The translations
Example output
{
  "count": 1,
  "has_more": false,
  "next_page_token": "",
  "translations": [
    {
      "audio_url": "https://files.heygen.ai/translate/5b2a7c9e1f3d4a6b.mp3",
      "created_at": 1761300300,
      "duration": 12.4,
      "failure_code": null,
      "failure_message": null,
      "id": "5b2a7c9e1f3d4a6b",
      "input_language": "en",
      "output_language": "Spanish (Spain)",
      "srt_caption_url": "https://files.heygen.ai/translate/5b2a7c9e1f3d4a6b.srt",
      "status": "completed",
      "title": "Welcome, Sam (Spanish)",
      "translate_audio_only": false,
      "video_url": "https://files.heygen.ai/translate/5b2a7c9e1f3d4a6b.mp4",
      "vtt_caption_url": "https://files.heygen.ai/translate/5b2a7c9e1f3d4a6b.vtt"
    }
  ]
}

List videos

List the account's videos with their status and download links, optionally only those whose title contains some text.

Inputs

Title containstitletext
Only videos whose title contains this.
Page sizelimitnumber
How many to return, 1 to 100.From 1 to 100.
Next pagepage_tokentext
The 'next_page_token' an earlier run of this step gave, to get the page after it.

Outputs

countnumber
How many on this page
has_moretrue/false
True when there are more after this page
next_page_tokentext
Give this as the Next page field to get the next page; empty on the last one
videoslist
The videos
Example output
{
  "count": 1,
  "has_more": false,
  "next_page_token": "",
  "videos": [
    {
      "captioned_video_url": null,
      "completed_at": 1761300180,
      "created_at": 1761300000,
      "duration": 12.4,
      "failure_code": null,
      "failure_message": null,
      "folder_id": null,
      "gif_url": null,
      "id": "8f3c2b1a9d4e4c7b",
      "output_language": null,
      "status": "completed",
      "subtitle_url": "https://files.heygen.ai/caption/8f3c2b1a9d4e4c7b.srt",
      "thumbnail_url": "https://files.heygen.ai/thumbnail/8f3c2b1a9d4e4c7b.jpg",
      "title": "Welcome, Sam",
      "video_page_url": "https://app.heygen.com/videos/8f3c2b1a9d4e4c7b",
      "video_url": "https://files.heygen.ai/video/8f3c2b1a9d4e4c7b.mp4"
    }
  ]
}

List voices

List voices from HeyGen's library or your own, by language and gender, with a sample of each.

Inputs

Libraryvoice_typetext
HeyGen's voice library, or your own voices.One of: public (HeyGen's voice library (default)), private (My own voices).
Languagelanguagetext
Only voices in this language, such as English.
Gendergendertext
Only voices of this gender.One of: female, male.
Page sizelimitnumber
How many to return, 1 to 100.From 1 to 100.
Next pagepage_tokentext
The 'next_page_token' an earlier run of this step gave, to get the page after it.

Outputs

countnumber
How many on this page
has_moretrue/false
True when there are more after this page
next_page_tokentext
Give this as the Next page field to get the next page; empty on the last one
voiceslist
The voices
Example output
{
  "count": 1,
  "has_more": false,
  "next_page_token": "",
  "voices": [
    {
      "default_engine": "starfish",
      "gender": "female",
      "language": "English",
      "name": "Allison",
      "preview_audio_url": "https://files.heygen.ai/voice/allison.mp3",
      "support_pause": true,
      "type": "public",
      "voice_id": "f38a635bee7a4d1f9b0a654a31d050d2"
    }
  ]
}

Translate video

Translate a video into one or more languages in the speaker's own voice, with lip-sync. Paid for by the minute from your HeyGen balance; follow with 'Wait for translation'.

Inputs

Video linkvideo_urltextRequired
A public link to the MP4 or WebM to translate, such as a HeyGen video's download link.
Translate intooutput_languageslistRequired
The languages to translate into: one translation each.
Titletitletext
The video's title in HeyGen.
Qualitymodetext
Faster, or better lip-sync. Defaults to speed.One of: speed (Speed: faster (default)), precision (Precision: better lip-sync).
Audio onlytranslate_audio_onlytrue/false
Yes translates the voice but leaves the lips as they are.
Speakersspeaker_countnumber
How many people speak, 1 to 10. Helps tell voices apart.From 1 to 10.
Remove background musicremove_background_musictrue/false
Yes drops the music track from the translation.

Outputs

countnumber
How many translations started
video_translation_idtext
The first translation's id, for 'Wait for translation'
video_translation_idslist
One translation id per language, in order
Example output
{
  "count": 1,
  "video_translation_id": "5b2a7c9e1f3d4a6b",
  "video_translation_ids": [
    "5b2a7c9e1f3d4a6b"
  ]
}

Upload file

Upload an image, video, audio file or PDF (up to 32 MB) to HeyGen and get a public link the photo, video and translation steps take.

Inputs

FilefiletextRequired
The file: upload one, pick one from an earlier step, or paste a public link to it. PNG, JPEG, MP4, WebM, MP3, WAV or PDF.

Outputs

The uploaded file

asset_idtext
The file's id in HeyGen
mime_typetext
The file's type, such as image/png
size_bytesnumber
The file's size in bytes
urltext
The file's public link, which video, photo and translation steps take
Example output
{
  "asset_id": "asset_abc123def456",
  "mime_type": "image/png",
  "size_bytes": 245760,
  "url": "https://files.heygen.ai/assets/asset_abc123def456.png"
}

Wait for translation

Wait until a translation is ready, then return its links. Fails with HeyGen's reason if it fails, or if it is still running when the wait runs out.

Inputs

Translation IDvideo_translation_idtextRequired
The translation's id, from 'Translate video' or 'List translations'.
Wait up to (minutes)max_minutesnumber
How long to wait, 1 to 30 minutes. Defaults to 10. A short video usually takes a few.From 1 to 30.

Outputs

readytrue/false
True once the translation is finished
statustext
pending, running, completed or failed
translationobject
The translation
video_translation_idtext
The translation's id
video_urltext
Download link for the translated video, empty until it is ready
Example output
{
  "ready": true,
  "status": "completed",
  "translation": {
    "audio_url": "https://files.heygen.ai/translate/5b2a7c9e1f3d4a6b.mp3",
    "created_at": 1761300300,
    "duration": 12.4,
    "failure_code": null,
    "failure_message": null,
    "id": "5b2a7c9e1f3d4a6b",
    "input_language": "en",
    "output_language": "Spanish (Spain)",
    "srt_caption_url": "https://files.heygen.ai/translate/5b2a7c9e1f3d4a6b.srt",
    "status": "completed",
    "title": "Welcome, Sam (Spanish)",
    "translate_audio_only": false,
    "video_url": "https://files.heygen.ai/translate/5b2a7c9e1f3d4a6b.mp4",
    "vtt_caption_url": "https://files.heygen.ai/translate/5b2a7c9e1f3d4a6b.vtt"
  },
  "video_translation_id": "5b2a7c9e1f3d4a6b",
  "video_url": "https://files.heygen.ai/translate/5b2a7c9e1f3d4a6b.mp4"
}

Wait for video

Wait until a video is ready, then return its download link. Fails with HeyGen's reason if the video fails, or if it is still rendering when the wait runs out.

Inputs

Video IDvideo_idtextRequired
The video's id, from a create step or 'List videos'.
Wait up to (minutes)max_minutesnumber
How long to wait, 1 to 30 minutes. Defaults to 10. A short video usually takes a few.From 1 to 30.

Outputs

readytrue/false
True once the video is finished
statustext
pending, processing, completed or failed
videoobject
The video
video_idtext
The video's id
video_urltext
Download link for the finished video, empty until it is ready. It expires after a while.
Example output
{
  "ready": true,
  "status": "completed",
  "video": {
    "captioned_video_url": null,
    "completed_at": 1761300180,
    "created_at": 1761300000,
    "duration": 12.4,
    "failure_code": null,
    "failure_message": null,
    "folder_id": null,
    "gif_url": null,
    "id": "8f3c2b1a9d4e4c7b",
    "output_language": null,
    "status": "completed",
    "subtitle_url": "https://files.heygen.ai/caption/8f3c2b1a9d4e4c7b.srt",
    "thumbnail_url": "https://files.heygen.ai/thumbnail/8f3c2b1a9d4e4c7b.jpg",
    "title": "Welcome, Sam",
    "video_page_url": "https://app.heygen.com/videos/8f3c2b1a9d4e4c7b",
    "video_url": "https://files.heygen.ai/video/8f3c2b1a9d4e4c7b.mp4"
  },
  "video_id": "8f3c2b1a9d4e4c7b",
  "video_url": "https://files.heygen.ai/video/8f3c2b1a9d4e4c7b.mp4"
}

On this page