2026-09-25Sume Avatar 1.0

Multi-scene avatar video API: build one video from ordered scenes

Send ordered video_inputs instead of one script to compose spoken and silent scenes into one 4-60 second avatar video. Scene fields, rules, and limits.

5 min readSume

All posts

A multi-scene avatar video on Sume is one composed talking-avatar video planned as an ordered video_inputs array instead of a single script. Each entry is a scene with a spoken or silent voice beat, so one request can carry a hook, a silent demo, and a call to action, as long as the total planned duration lands in the 4-60 second window.

Every detail below comes from the multi-scene section of Generate avatar video.

When should I use video_inputs instead of a script?

POST /v1/avatar-1.0/talking-video takes exactly one of script or video_inputs. Use ordered video_inputs when you need scene hooks, demos, or silence beats in one composed video. For a single script, see Talking avatar video API.

What does a multi-scene request look like?

This request follows the docs example, with a placeholder handle and new spoken text: a spoken hook, a silent demo beat, and a spoken call to action. Each scene also names a background.

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-multi-001" \
  -d '{
    "avatar_handle": "product_host",
    "aspect_ratio": "9:16",
    "quality": "plus",
    "video_inputs": [
      {
        "id": "hook",
        "voice": { "type": "text", "script": "Three things to know before you buy a travel mug.", "duration": 3 },
        "background": { "type": "prompt", "prompt": "Casual kitchen framing, natural light" }
      },
      {
        "id": "demo",
        "voice": { "type": "silence", "duration": 4 },
        "background": { "type": "prompt", "prompt": "Casual kitchen framing, natural light" }
      },
      {
        "id": "cta",
        "voice": { "type": "text", "input_text": "Tap the link to see the Acme mug in every color.", "duration": 5 },
        "background": { "type": "prompt", "prompt": "Casual kitchen framing, natural light" }
      }
    ]
  }'

Which fields does each scene take?

Reference the avatar with top-level avatar_handle; the docs also allow per-scene character fields inside video_inputs. The example sets aspect_ratio and quality at the top level, beside video_inputs.

From Generate avatar video, read 2026-09-25.
Scene field	What the docs say
`id`	A scene id. The docs example uses `hook`, `demo`, and `cta`.
`voice.type: "text"`	A spoken scene. Takes exactly one of `script` or `input_text`.
`voice.type: "silence"`	A non-speaking beat. `duration` is required; `script` and `input_text` are not allowed.
`voice.duration`	Required on silence beats. The docs example also sets it on spoken scenes.
`background`	Scene direction, such as `{ "type": "prompt", "prompt": "..." }`. Current execution expects backgrounds to resolve to one shared scene.

What limits apply to a multi-scene plan?

Total planned duration must land in the 4-60 second window.
A request carries exactly one of script or video_inputs.
Current execution supports one resolved avatar per final video.
Current execution expects scene backgrounds to resolve to one shared scene.
aspect_ratio supports 1:1, 3:4, 9:16, 4:3, and 16:9 (default 9:16); resolution is currently 720p.
Media fields must be fetchable public HTTPS URLs.

Can I caption or preview a multi-scene video?

Yes. Optional captions burns styles into the clean final MP4 after generation, using the video_inputs text; slam is the default style. Caption stage failures soft-fail: the avatar job can still succeed with a clean primary video_url and captions.status=failed.

To review first-frame stills before paying for a full render, create an avatar video preview, then call generate-video on the preview id. Completed results can include preview_image_url and scene_previews; Avatar video previews: approve the first frame covers per-scene stills.

How much does a multi-scene avatar video cost?

A multi-scene plan goes to the same Avatar Video endpoint and quality tiers as a single script: standard, plus (the default), and max. 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.

Sources

Written by Sume