Generate avatar video

Avatar videos turn a ready avatar into a script-driven talking video. Prefer the canonical Avatar 1.0 route:

Launch requests reference a ready avatar with top-level avatar_handle (or per-scene character fields inside video_inputs). Provide exactly one of script or video_inputs.

Scripts and multi-scene plans are accepted when Sume estimates the target video duration at 4-60 seconds inclusive. Shorten longer scripts or split them into multiple jobs.

Create an avatar video

Create an avatar talking video

POST /v1/avatar-1.0/talking-video

Required

Optional product and scene inputs

  • Omit product_image for a productless avatar video.
  • Use scene: { "type": "prompt", "prompt": "..." } for scene direction.
  • Use scene: { "type": "photo", "image_url": "https://..." } for a photo scene reference.
  • Media fields must be fetchable public HTTPS URLs. See Media inputs.

Quality

Avatar Video accepts quality: "standard" | "plus" | "max".

ValueBehavior
plusDefault when omitted. Balanced quality path.
standardFastest Sume execution path.
maxHighest quality tier; slower turnaround.

Aspect ratio and resolution

  • aspect_ratio supports 1:1, 3:4, 9:16, 4:3, and 16:9. Default: 9:16.
  • resolution is currently 720p.

video_inputs

Use ordered video_inputs instead of a single script when you need scene hooks, demos, or silence beats in one composed video. Total planned duration must still land in the 4-60 second window.

voice.type: "silence" is a non-speaking beat: duration is required, and script / input_text are not allowed. Spoken scenes still use type: "text" with exactly one of script or input_text.

Current execution supports one resolved avatar per final video and expects scene backgrounds to resolve to one shared scene.

Inline captions

Optional captions burns styles into the clean final MP4 after generation, using the spoken script / video_inputs text. Preview stills are never captioned.

  • captions 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 style: "slam" (or punch / tiktok-green) is rejected with 400 caption_hangul_text_latin_style rather than re-styled — those faces render Hangul as tofu. 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. For captioning an existing public video URL, use Video captions.

Poll and recover

Completed results can include public media.sume.com video artifacts plus public-safe preview fields such as preview_image_url and scene_previews.

Read avatar-video resources

Preview first, then generate

To review first-frame stills before paying for a full render, create an Avatar video preview, then call generate-video on the preview id.

Compatibility aliases

AliasNotes
POST /v1/models/sume/avatar-1.0/talking-video/runsCanonical model-run alias. Prefer /v1/avatar-1.0/talking-video for new integrations.
POST /v1/models/sume/avatar-video/v1.0/runsLegacy launch alias. Same body contract.