Generate avatar video

Avatar videos change a ready avatar into a script-driven talking video. The canonical Avatar 1.0 route is preferred:

POST /v1/avatar-1.0/talking-video

Launch requests use the top-level avatar_handle (or per-scene character fields inside video_inputs) to identify a ready avatar. Provide one of script or video_inputs, not both.

Each avatar video is one clip. Sume accepts scripts and multi-scene plans when it estimates the target video duration at 4-12 seconds inclusive, and refuses a longer one before any work starts. Make longer scripts shorter, or split them into multiple jobs.

Create an avatar video

curl -sS -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: $(uuidgen)" \
  -d '{"avatar_handle":"sume_clawra","script":"Say hello to the Sume developer platform.","product_image":"https://example.com/product.png","scene":{"type":"prompt","prompt":"Bright studio with clean product table"},"quality":"plus","resolution":"720p","aspect_ratio":"9:16"}'

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. Refer to Media inputs.

Quality

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

Aspect ratio and resolution

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

Multi-scene video_inputs

For scene hooks, demos, or silence beats in one video, use ordered video_inputs, not a single script. All scenes go into the same single clip, so the total planned duration must still be in the 4-12 second window.

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": "sume_clawra",
    "aspect_ratio": "9:16",
    "quality": "plus",
    "video_inputs": [
      {
        "id": "hook",
        "voice": {
          "type": "text",
          "script": "Wait, this turned one selfie into a whole video?",
          "duration": 3
        },
        "background": {
          "type": "prompt",
          "prompt": "Casual bedroom framing, native UGC lighting"
        }
      },
      {
        "id": "demo",
        "voice": {
          "type": "silence",
          "duration": 4
        },
        "background": {
          "type": "prompt",
          "prompt": "Casual bedroom framing, native UGC lighting"
        }
      },
      {
        "id": "cta",
        "voice": {
          "type": "text",
          "input_text": "You pick a template, drop in your photo, and it builds the clip around you.",
          "duration": 5
        },
        "background": {
          "type": "prompt",
          "prompt": "Casual bedroom framing, native UGC lighting"
        }
      }
    ]
  }'

voice.type: "silence" is a beat with no speech. duration is required, and script / input_text are not permitted. Spoken scenes still use type: "text" with one of script or input_text, not both.

The current execution supports one resolved avatar for each final video. It also expects that the scene backgrounds resolve to one shared scene.

Inline captions

After generation, the optional captions burns styles into the clean final MP4. It uses the spoken script / video_inputs text. Sume never adds captions to preview stills.

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

• captions takes the same four settings 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), and the Hangul identities weight-shift, black-outline, highlight, pill-karaoke, clip-wipe and editorial-emphasis.
• If a Korean script uses style: "slam" (or punch / tiktok-green), Sume rejects it with 400 caption_hangul_text_latin_style. Sume does not change the style. Those font faces render Hangul as tofu. For Korean speech, select a Hangul style.
• A failure in the caption stage is a soft failure. 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 add captions to a public video URL that you already have, use Video captions.

Poll and recover

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"

Completed results can include public media.sume.com video artifacts. They can also include public-safe preview fields, for example preview_image_url and scene_previews.

Read avatar-video resources

curl https://api.sume.com/v1/avatar-videos \
  -H "Authorization: Bearer $SUME_API_KEY"

curl https://api.sume.com/v1/avatar-videos/avatar_video_123 \
  -H "Authorization: Bearer $SUME_API_KEY"

Preview first, then generate

To review first-frame stills before you use credits on a full render, create an Avatar video preview. Then call generate-video on the preview id.

Compatibility aliases

Related

• Create new avatar
• Avatar video previews
• Face swap (Beta)
• Video captions
• Jobs and results