Talking avatar video API: generate an avatar video from a script

Sume's talking avatar video API turns a ready avatar and a script into a talking video. Send POST /v1/avatar-1.0/talking-video with an avatar_handle and a script that Sume estimates at 4-60 seconds. The request runs as a job, and completed results can include public media.sume.com video artifacts.

Every detail below comes from the Generate avatar video docs page.

What do I need before I call it?

• A ready avatar, referenced by the top-level avatar_handle. How to create a reusable AI avatar shows how to make one.
• Exactly one of script or video_inputs. This guide uses script; ordered scenes are covered in Multi-scene avatar video API.
• A script Sume estimates at 4-60 seconds inclusive. Shorten a longer script or split it into multiple jobs.
• Fetchable public HTTPS URLs for any media fields, such as product_image or a photo scene.

What does a request look like?

This request makes a productless 9:16 video with a prompted scene. Omit product_image for a productless avatar video, or pass it as an optional product reference.

Prefer /v1/avatar-1.0/talking-video for new integrations. The compatibility aliases are POST /v1/models/sume/avatar-1.0/talking-video/runs (canonical model-run alias) and POST /v1/models/sume/avatar-video/v1.0/runs (legacy launch alias, same body contract).

curl -X POST https://api.sume.com/v1/avatar-1.0/talking-video \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: avatar-video-001" \
  -d '{
    "avatar_handle": "product_host",
    "script": "Meet the Acme travel mug. It fits every cup holder and every bag.",
    "scene": { "type": "prompt", "prompt": "Bright kitchen counter, morning light" },
    "quality": "plus",
    "aspect_ratio": "9:16"
  }'

Which options can I set?

Which quality tier should I pick?

Per-second rates are $0.184/s standard, $0.245/s plus, $0.55/s max (no product image), and the default 5.5% agent fee applies on top. Rates with a product image are on API pricing. The docs describe the three tiers this way:

• plus: the default when omitted. "Balanced quality path."
• standard: "Fastest Sume execution path."
• max: "Highest quality tier; slower turnaround."

Can Sume burn captions into the avatar video?

Yes. Optional captions burns styles into the clean final MP4 after generation, using the spoken script. It takes the same four knobs as standalone Video captions: style, optional font, a language hint, and script_text.

• Styles: slam (default), punch, tiktok-green, korean-ad (Hangul karaoke for Korean speech), plus the Hangul identities weight-shift, black-outline, highlight, pill-karaoke, clip-wipe, and editorial-emphasis.
• A Korean script with slam, punch, or tiktok-green is rejected with 400 caption_hangul_text_latin_style. Pick a Hangul style for Korean speech.
• Estimated duration above 60 seconds is rejected for inline captions.
• Caption stage failures soft-fail: the avatar job can still succeed with a clean primary video_url and captions.status=failed.
• Inline captions do not create a separate billed video-caption job. To caption an existing public video URL, use Video captions.

{
  "captions": {
    "enabled": true,
    "style": "slam",
    "language": "auto"
  }
}

How do I get the finished video?

Poll the job status, read its events, and fetch the result. Completed results can include public media.sume.com video artifacts plus public-safe preview fields such as preview_image_url and scene_previews. To list or read avatar-video resources later, call GET /v1/avatar-videos or GET /v1/avatar-videos/avatar_video_123.

curl https://api.sume.com/v1/jobs/job_123/status \
  -H "Authorization: Bearer $SUME_API_KEY"

curl https://api.sume.com/v1/jobs/job_123/events \
  -H "Authorization: Bearer $SUME_API_KEY"

curl https://api.sume.com/v1/jobs/job_123/result \
  -H "Authorization: Bearer $SUME_API_KEY"

Can I check the first frame before paying for a full render?

Yes. To review first-frame stills before paying for a full render, create an avatar video preview first, then call generate-video on the preview id. Avatar video previews: approve the first frame covers that flow.