heygen/avatar5/digital-twin
Avatar5 Digital Twin by HeyGen - generate cinematic videos from text descriptions with AI. Create high-quality video content with natural motion, camera control, and optional audio generation.
Example output — click Run to generate your own
Send your first request
OpenAI-compatible endpoint with unified authentication and usage tracking.
https://api.sandbase.ai/v1/runheygen/avatar5/digital-twinInput Schema
12 parameters · 1 required · 11 optional
| Parameter | Type | Required | Description |
|---|---|---|---|
prompt | string | Required | Text the avatar will speak. Required when ``audio_url`` is not provided. |
fit | string | Optional | How the avatar fits within the output frame. 'contain' keeps the full avatar in view (may letterbox); 'cover' fills the frame (may crop). · Options: contain, cover · Default: "cover" containcover |
audio | string | Optional | HTTP(S) URL of an audio file for the avatar to lip-sync to. When provided, the avatar uses this audio instead of text-to-speech and ``prompt``/``voice`` are ignored. |
voice | string | Optional | Name of the text-to-speech voice to use for the avatar when ``audio_url`` is not provided. · Options: Warm Pro Narrator, Chill Brian, Ivy, John Doe, Monika Sogam, Hope , Archer , Brittney, Patrick, David Castlemore, Michael C, Adam Stone , Juniper, Cassidy , Jessica Anne Bogart, Arabella, Andrew, Spuds Oxley , Grace Elder, Helen, Canyon Rivers, Derya - Lifelike - Excited 🤩, Mellow Marcus, Jack Sterling - Broadcaster 🎙️, Brenda - UGC - 1.mp4, Reid, Reagan, Terry, Jenny, Radio Rick, Denise, Tim in car - Excited 🤩, Iskander, Thompson, Delicate Daisy - Excited 🤩, Kingston, George UGC 1, Bold Blake, Jane, Expressive Evan, Marianne - IA, Aaron, Modern Recipe Host - Voice 1, Willow, Cute Chloe - Friendly 😊, Rafael, June - Lifelike, Crisp Chloe, Slick Simon, Nassim - Informative, Baritone Ben, Maxwell, Ellie Faye - Excited 🤩, Milani, Feisty Fiona - Excited 🤩, Professor Dean, Rose - UGC - 1.mp4, Shona, Hudson Wilder, Ann - IA, Alastair Kensington, Oxley, Christina, Andrew Rizz , Peyton, Gerardo - Outdoor, Chloe - Lifelike, Stephanie, Anthony - IA, Signal - Voice 1, Luca, Lisa - Voice 1, T.W.Tucker, Jack Sullivan - Serious 😐, Winter, Mireia - Lifelike, Georgia, Stella, Masha - Lifelike, Charming Charles - Friendly 😊, Serenity, Annie - Excited, Ralph, Bethany, Dominic, Mason Finn, Leena, Veteran Victor, Tamara, Nik Public, Calm Chloe, Sevik, Reilly, Raul, Imposing Ian, Relaxed Ray, Dexter - Professional, Relaxed Rick, Edwin, Rupert Blackwood, Ginny, Hope · Default: "Warm Pro Narrator" Warm Pro NarratorChill BrianIvyJohn DoeMonika SogamHope Archer BrittneyPatrickDavid CastlemoreMichael CAdam Stone JuniperCassidy Jessica Anne BogartArabellaAndrewSpuds Oxley Grace ElderHelenCanyon RiversDerya - Lifelike - Excited 🤩Mellow MarcusJack Sterling - Broadcaster 🎙️Brenda - UGC - 1.mp4ReidReaganTerryJennyRadio RickDeniseTim in car - Excited 🤩IskanderThompsonDelicate Daisy - Excited 🤩KingstonGeorge UGC 1Bold BlakeJaneExpressive EvanMarianne - IAAaronModern Recipe Host - Voice 1WillowCute Chloe - Friendly 😊RafaelJune - LifelikeCrisp ChloeSlick SimonNassim - InformativeBaritone BenMaxwellEllie Faye - Excited 🤩MilaniFeisty Fiona - Excited 🤩Professor DeanRose - UGC - 1.mp4ShonaHudson WilderAnn - IAAlastair KensingtonOxleyChristinaAndrew Rizz PeytonGerardo - OutdoorChloe - LifelikeStephanieAnthony - IASignal - Voice 1LucaLisa - Voice 1T.W.TuckerJack Sullivan - Serious 😐WinterMireia - LifelikeGeorgiaStellaMasha - LifelikeCharming Charles - Friendly 😊SerenityAnnie - ExcitedRalphBethanyDominicMason FinnLeenaVeteran VictorTamaraNik PublicCalm ChloeSevikReillyRaulImposing IanRelaxed RayDexter - ProfessionalRelaxed RickEdwinRupert BlackwoodGinnyHope |
avatar | string | Optional | Name of the Avatar V-eligible avatar to use. · Default: "Abigail Sofa Front" |
caption | boolean | Optional | Generate a sidecar SRT caption file alongside the video. · Default: false |
watermark | string | Optional | Optional watermark image to overlay on the output video. |
background | string | Optional | Optional background to composite behind the avatar. Ignored when ``output_format='webm'`` (webm output is transparent). |
resolution | string | Optional | Output resolution preset. · Options: 720p, 1080p, 4k · Default: "720p" 720p1080p4k |
aspect_ratio | string | Optional | The aspect ratio of the generated image. · Options: 21:9, 16:9, 3:2, 4:3, 5:4, 1:1, 4:5, 3:4, 2:3, 9:16 21:916:93:24:35:41:14:53:42:39:16 |
output_format | string | Optional | Output container format. 'webm' produces a transparent video (automatically removes the background) and ignores the ``background`` field. · Options: mp4, webm · Default: "mp4" mp4webm |
remove_background | boolean | Optional | Remove the avatar's background. Requires a matting-enabled avatar. · Default: false |
Output Schema
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the generation task |
status | string | Task status: pending, running, completed, failed, timeout |
model | string | Model used for the generation |
outputs | array | Array of output items |
outputs[].url | string | URL of the generated artifact |
outputs[].content_type | string | MIME type (e.g. image/png, video/mp4) |
error | object | null | Error details if failed, null on success |
error.type | string | Machine-readable error type code |
error.message | string | Human-readable error description |
Async Workflow
This model uses asynchronous execution. Submit a request and poll for the result.
- Submit — POST to /v1/run, receive an
id - Poll — GET /v1/run/{id} until status is
completed,failed, ortimeout - Retrieve — Read
outputsfrom the completed response
Code Examples
Ready-to-run snippets
# Step 1: Submit
curl -X POST https://api.sandbase.ai/v1/run \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"model": "heygen/avatar5/digital-twin",
"fit": "cover",
"voice": "Warm Pro Narrator",
"avatar": "Abigail Office Front",
"prompt": "Hello and welcome to this demonstration of HeyGen Avatar V.",
"caption": false,
"resolution": "720p",
"output_format": "mp4",
"remove_background": false
}'
# Step 2: Poll result (replace <id>)
curl https://api.sandbase.ai/v1/run/<id> \
-H "Authorization: Bearer YOUR_API_KEY"API README
Heygen v5 Digital Twin
heygen/avatar5/digital-twin creates a talking digital-human video whose facial movement, timing, and expression follow supplied speech or creative direction. Avatar 5 builds a highly expressive digital twin with improved facial realism, emotion, gesture, and speech synchronization for presenter performances. This combination makes the model a practical choice when the creative outcome depends on those qualities rather than on a generic media conversion.
For production work with heygen/avatar5/digital-twin, the workflow suits explainers, training, localization, personalized outreach, and presenter-led content where a reusable human presence needs to deliver changing material. The result is most reliable when the source material and creative brief clearly describe the intended subject, progression, visual or sonic character, and the qualities that must remain unchanged.
Highlights
Speech-driven facial animation aligns mouth shapes, expression, and timing with the performance.
Avatar 5 realism captures subtle facial expression, emotion, and lifelike presenter behavior.
Presenter consistency supports repeated videos without reshooting the same person.
Expressive performance turns scripted material into an engaging on-camera delivery.
Pricing
| Generated or processed duration | Price |
|---|---|
| Per second | $0.100 |
When to Use
| ✅ Good fit | ❌ Consider alternatives |
|---|---|
| The model's named workflow matches the source material and intended output | A different input modality or model route is required |
| A managed asynchronous result is suitable for the production pipeline | A synchronous, interactive editor is essential |
| The documented controls cover the required duration, framing, or format | The project needs controls outside this endpoint's schema |
| Creative iteration benefits from a repeatable request structure | Exact deterministic pixels, frames, geometry, or samples are mandatory |
| A finished downloadable media asset is the desired deliverable | Editable source layers or a native project file are required |
Prompt Guide
For audio transformation, state the intended result first, then add the subject or source treatment, progression, style, and delivery constraints. Keep one creative variable per phrase, use the documented field names for controls, and change one setting at a time when comparing results.
{
"aspect_ratio": "21:9",
"audio": "https://example.com/source.wav",
"output_format": "mp4",
"prompt": "Hello and welcome to this demonstration of HeyGen Avatar V.",
"resolution": "720p"
}
Technical Specs
| Spec | Value |
|---|---|
| Model ID | heygen/avatar5/digital-twin |
| Inputs | aspect_ratio, audio, avatar, background, caption, fit, output_format, prompt, remove_background, resolution, voice, watermark |
| Required inputs | prompt |
| Output fields | content_type, url |
| Execution | Async (submit, then poll for result) |
| Resolution | 720p / 1080p / 4k |
| Aspect Ratio | 21:9 / 16:9 / 3:2 / 4:3 / 5:4 / 1:1 / 4:5 / 3:4 / 2:3 / 9:16 |
| Output Format | mp4 / webm |

