---
title: Generate avatar video
description: Generate talking avatar videos from a ready avatar, script or multi-scene inputs, and optional product or scene references.
---

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

```text
POST /v1/avatar-1.0/talking-video
```

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

<!-- api-call-example:avatar-talking-video -->

### 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](/workflows/asset-library).

### Quality

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

| Value | Behavior |
|---|---|
| `plus` | **Default** when omitted. Balanced quality path. |
| `standard` | Fastest Sume execution path. |
| `max` | Highest 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`.

## Multi-scene `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.

```bash
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 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.

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

- `captions` takes the same four knobs as standalone
  [Video captions](/models/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](/models/video-captions).

## Poll and recover

```bash
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 plus
public-safe preview fields such as `preview_image_url` and `scene_previews`.

## Read avatar-video resources

```bash
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 paying for a full render, create an
[Avatar video preview](/models/avatar-video-previews), then call
`generate-video` on the preview id.

## Compatibility aliases

| Alias | Notes |
|---|---|
| `POST /v1/models/sume/avatar-1.0/talking-video/runs` | Canonical model-run alias. Prefer `/v1/avatar-1.0/talking-video` for new integrations. |
| `POST /v1/models/sume/avatar-video/v1.0/runs` | Legacy launch alias. Same body contract. |

## Related

- [Create new avatar](/models/avatar)
- [Avatar video previews](/models/avatar-video-previews)
- [Face swap (Beta)](/models/face-swap)
- [Video captions](/models/video-captions)
- [Jobs and results](/workflows/jobs-and-results)