---
title: Avatar video previews
description: Create first-frame Avatar Video previews, regenerate stills, then generate the final video.
---

Avatar video previews generate the first-frame still stage without starting the
full talking-video render. Use them when you want to approve composition before
spending a full Avatar Video generation.

```text
POST /v1/avatar-video-previews
GET  /v1/avatar-video-previews/:id
POST /v1/avatar-video-previews/:id/regenerate
POST /v1/avatar-video-previews/:id/generate-video
```

## When to use

- Review scene framing / first frames before a full render.
- Multi-scene `video_inputs` where you want one still per scene.
- Store caption intent on create, then apply captions only at
  `generate-video` time (preview stills are never caption-burned).

For a direct full render without the preview stage, use
[Generate avatar video](/models/avatar-videos).

## Create a preview

The create body matches Avatar Video fields: provide exactly one of `script` or
`video_inputs`, plus optional `product_image`, `scene`, `quality`,
`aspect_ratio`, `title`, and `captions`.

`quality` defaults to **`plus`** when omitted (`standard` | `plus` | `max`).

<!-- api-call-example:avatar-video-preview-create -->

The response includes job polling URLs plus an `avatar_video_preview_id`. Poll
the job like any other generation:

```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/result \
  -H "Authorization: Bearer $SUME_API_KEY"
```

## Read the preview resource

```bash
curl https://api.sume.com/v1/avatar-video-previews/avp_123 \
  -H "Authorization: Bearer $SUME_API_KEY"
```

When ready, public-safe fields include:

- `preview_image_url` — primary still (scene 0 for multi-scene).
- `scene_previews[]` — one still per input scene when available.
- `resource_status` / `job_status` — prefer these over the legacy `status`
  field for readiness vs job polling.

For multi-scene previews with a shared scene, later scene stills are
pose-anchored continuations of the first frame.

## Regenerate stills

Reuse the stored preview request (avatar, script/`video_inputs`, scene,
quality, aspect ratio) and only refresh first-frame stills:

<!-- api-call-example:avatar-video-preview-regenerate -->

Returns the same `avatar_video_preview_id` with a new preview-only job.

## Generate the final video

When the preview looks right, start the normal Avatar Video workflow from the
preview id. Sume reuses the preview first frame when available. Captions stored
on preview create apply at this step.

Empty body (or `{}`) keeps the quality chosen at preview create. Optional
`quality` overrides the **final render** tier only — preview stills are
tier-independent and always reused, so approve-then-downgrade/upgrade does not
require a new preview.

<!-- api-call-example:avatar-video-preview-generate -->

Admission, pre-spend, ledger reservation, provider submit, and readback all
use the effective (overridden) tier. Structural fields (`script`,
`video_inputs`, `avatar_handle`, `scene`, `aspect_ratio`) still require a new
preview.

Poll the returned job, then read the avatar-video resource:

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

## Constraints

- Same duration window as Avatar Video: estimated 4-60 seconds inclusive.
- Media inputs are URL-first public HTTPS fields (`product_image`,
  `scene.image_url`, and any scene background image URLs).
- Inline captions on preview create are stored for `generate-video`; they are
  not burned into preview stills.
- Preview stills are tier-independent; `generate-video` `quality` only changes
  the final video provider tier.
- Exact request/response schemas: live
  [OpenAPI](https://api.sume.com/reference/json).

## Related

- [Generate avatar video](/models/avatar-videos)
- [Video captions](/models/video-captions) (standalone caption jobs)
- [Jobs and results](/workflows/jobs-and-results)