HeyGen Avatar IV
POST Base URL:
https://api.hiapi.ai /v1/tasks Image, video, and audio models are called through theUnified Async API POST /v1/tasks endpoint; only the input fields differ (see input parameters below).
Model summary
| Model | heygen-avatar-iv |
|---|---|
| Capability | Photo avatar video |
| Driving method | Script and voice / driving audio |
| Output | MP4, 720p / 1080p |
Turn one portrait photo into a lip-synced talking video from a script or driving audio.
Production guidance
Calling the API
- Use exactly one of prompt or audio_url.
- Pass the photo, audio and background image as publicly accessible HTTPS URLs.
- Use a front-facing portrait with even lighting and an unobstructed face.
- Use callback.url for terminal notifications and GET /v1/tasks/:id as a fallback query.
Best suited for
Script and voice
Send a photo and a script, then pick a voice to generate a presenter video.
image_urlpromptvoiceDriving audio
Send a photo and existing audio to drive lip-sync directly.
image_urlaudio_urlVertical short video
Output 9:16 and fill the area outside the portrait with a background.
aspect_ratiobackgroundRequest parameters
model string required Model ID.
input object required HeyGen Avatar IV parameters.
image_url string required Photo of the person who speaks in the video; it needs one clear face.
prompt string optional Script the person in the photo speaks, up to 5,000 characters. Use either prompt or audio_url.
voice string optional Voice used for script-driven video. See all voice presets ↓
audio_url string optional Audio that drives lip-sync; the person speaks along with this recording, up to 600 seconds. Use either audio_url or prompt.
resolution enum optional Output video resolution.
aspect_ratio enum optional Aspect ratio of the video, such as landscape 16:9 or vertical 9:16; auto keeps the photo ratio.
background object optional Fills the area outside the portrait when the aspect ratio differs from the photo; white when omitted.
type enum required Background type.
value string required #RRGGBB for color, or an image HTTPS URL for image.
callback object optional Sends the task object when the task reaches a terminal state.
url string required HTTPS URL that receives terminal notifications.
when enum optional Triggers on terminal status.
Voice presets (102)
Pass the exact Request value shown on each card in input.voice.
Show all 102 voice presets Hide all 102 voice presets
Request value
Warm Pro Narrator Request value
Chill Brian Request value
Ivy Request value
John Doe Request value
Monika Sogam Request value
Hope Request value
Archer Request value
Brittney Request value
Patrick Request value
David Castlemore Request value
Michael C Request value
Adam Stone Request value
Juniper Request value
Cassidy Request value
Jessica Anne Bogart Request value
Arabella Request value
Andrew Request value
Spuds Oxley Request value
Grace Elder Request value
Helen Request value
Canyon Rivers Request value
Derya - Lifelike - Excited Request value
Mellow Marcus Request value
Jack Sterling - Broadcaster Request value
Brenda - UGC - 1.mp4 Request value
Reid Request value
Reagan Request value
Terry Request value
Jenny Request value
Radio Rick Request value
Denise Request value
Tim in car - Excited Request value
Iskander Request value
Thompson Request value
Delicate Daisy - Excited Request value
Kingston Request value
George UGC 1 Request value
Bold Blake Request value
Jane Request value
Expressive Evan Request value
Marianne - IA Request value
Aaron Request value
Modern Recipe Host - Voice 1 Request value
Willow Request value
Cute Chloe - Friendly Request value
Rafael Request value
June - Lifelike Request value
Crisp Chloe Request value
Slick Simon Request value
Nassim - Informative Request value
Baritone Ben Request value
Maxwell Request value
Ellie Faye - Excited Request value
Milani Request value
Feisty Fiona - Excited Request value
Professor Dean Request value
Rose - UGC - 1.mp4 Request value
Shona Request value
Hudson Wilder Request value
Ann - IA Request value
Alastair Kensington Request value
Oxley Request value
Christina Request value
Andrew Rizz Request value
Peyton Request value
Gerardo - Outdoor Request value
Chloe - Lifelike Request value
Stephanie Request value
Anthony - IA Request value
Signal - Voice 1 Request value
Luca Request value
Lisa - Voice 1 Request value
T.W.Tucker Request value
Jack Sullivan - Serious Request value
Winter Request value
Mireia - Lifelike Request value
Georgia Request value
Stella Request value
Masha - Lifelike Request value
Charming Charles - Friendly Request value
Serenity Request value
Annie - Excited Request value
Ralph Request value
Bethany Request value
Dominic Request value
Mason Finn Request value
Leena Request value
Veteran Victor Request value
Tamara Request value
Nik Public Request value
Calm Chloe Request value
Sevik Request value
Reilly Request value
Raul Request value
Imposing Ian Request value
Relaxed Ray Request value
Dexter - Professional Request value
Relaxed Rick Request value
Edwin Request value
Rupert Blackwood Request value
Ginny Request value
Hope No matching voice values
Example requests
Script and voice, 1080p landscape
Generate a landscape presenter video from a photo and script.
Request body
{
"model": "heygen-avatar-iv",
"input": {
"image_url": "https://example.com/portrait.png",
"prompt": "Hi, I'm Lin. With one photo and a short script, I can present your product or record a lesson, with natural lip-sync and expressions.",
"voice": "Cute Chloe - Friendly",
"resolution": "1080p",
"aspect_ratio": "16:9"
}
}Driving audio, vertical with background
Drive lip-sync from existing audio and fill the 9:16 frame with a solid color.
Request body
{
"model": "heygen-avatar-iv",
"input": {
"image_url": "https://example.com/portrait.png",
"audio_url": "https://example.com/voice.mp3",
"resolution": "720p",
"aspect_ratio": "9:16",
"background": {
"type": "color",
"value": "#F5EFE6"
}
}
}Getting the result
- Read data.taskId after creating the task.
- Wait for the callback or query GET /v1/tasks/:id.
- On status=success, read the video URL from the output item whose type is video.