Heygen v5 Digital Twin

POST/v1/run

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.

Request body

Submit an async generation request. The model field selects the model; other fields are model-specific input parameters.

stringmodelrequired

Model identifier. Set to heygen/avatar5/digital-twin.

Default: heygen/avatar5/digital-twin

stringpromptrequired

Text the avatar will speak. Required when ``audio_url`` is not provided.

Optional<string>aspect_ratio

The aspect ratio of the generated image.

Allowed values: 21:9, 16:9, 3:2, 4:3, 5:4, 1:1, 4:5, 3:4, 2:3, 9:16

Optional<string>audio

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.

Optional<string>resolution

Output resolution preset.

Allowed values: 720p, 1080p, 4k

Default: 720p

Optional<string>output_format

Output container format. 'webm' produces a transparent video (automatically removes the background) and ignores the ``background`` field.

Allowed values: mp4, webm

Default: mp4

Optional<boolean>remove_background

Remove the avatar's background. Requires a matting-enabled avatar.

Default: false

Optional<string>avatar

Name of the Avatar V-eligible avatar to use.

Default: Abigail Sofa Front

Optional<string>voice

Name of the text-to-speech voice to use for the avatar when ``audio_url`` is not provided.

Allowed values: 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

Optional<boolean>caption

Generate a sidecar SRT caption file alongside the video.

Default: false

Optional<string>watermark

Optional watermark image to overlay on the output video.

Optional<string>background

Optional background to composite behind the avatar. Ignored when ``output_format='webm'`` (webm output is transparent).

Optional<string>fit

How the avatar fits within the output frame. 'contain' keeps the full avatar in view (may letterbox); 'cover' fills the frame (may crop).

Allowed values: contain, cover

Default: cover

Response Schema

The submit endpoint returns an accepted generation task. Poll the result endpoint with the returned id for terminal outputs or errors.

Optional<string>error

Error message if the task failed. Empty on success.

stringidrequired

Unique identifier for the generation task.

Optional<string>model

Model ID used for the prediction.

Optional<array>outputs

Array of generated content. Empty when status is not completed.

stringstatusrequired

Status of the task: pending, running, completed, failed, or timeout.

Allowed values: pending, running, completed, failed, timeout

Model capabilities

array<string>capability_tagsrequired

Capabilities declared by the model registry.

Default: text-to-video

stringexecution_moderequired

Execution mode declared by the model registry.

Default: async

# 1. Submit a generation request
curl -X POST https://api.sandbase.ai/v1/run \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "heygen/avatar5/digital-twin",
  "prompt": "Hello and welcome to this demonstration of HeyGen Avatar V.",
  "aspect_ratio": "21:9",
  "audio": "https://static.sandbase.ai/examples/input.mp3",
  "output_format": "mp4",
  "voice": "Warm Pro Narrator"
}'

# 2. If the response is still running, poll the returned id
curl https://api.sandbase.ai/v1/run/run_abc123 \
  -H "Authorization: Bearer $SANDBASE_API_KEY"

Response202 Accepted

{
  "id": "run_abc123",
  "model": "heygen/avatar5/digital-twin",
  "status": "running",
  "outputs": []
}