---
title: Models overview
description: Sume generation families — Avatar, Image, Video, Music, and related utilities.
---

Sume exposes job-backed generation families on the public Developer API. Each
family has a primary product URL plus, for most families, a model-run alias.
Submit a request with an `Idempotency-Key`, poll the job, then read the result.

Use [catalog](/api/reference) (`GET /v1/catalog`) and the OpenAPI snapshot to
discover current production capabilities. Deep guides below match the
**production** OpenAPI request schemas (`api.sume.com` / docs snapshot).

## Avatar 1.0

Avatar 1.0 is a two-step workflow:

1. Create a reusable avatar.
2. Use that avatar to generate talking videos from scripts or multi-scene
   inputs.

Prefer the canonical product routes for new integrations:

| Step | Canonical route |
|---|---|
| Create avatar | `POST /v1/avatar-1.0/generate` |
| List / read avatars | `GET /v1/avatar-1.0/avatars`, `GET /v1/avatar-1.0/avatars/:id` |
| Create talking video | `POST /v1/avatar-1.0/talking-video` |
| List / read videos | `GET /v1/avatar-videos`, `GET /v1/avatar-videos/:id` |

Legacy model-run aliases such as
`POST /v1/models/sume/avatar/v1.0/runs` and
`POST /v1/models/sume/avatar-video/v1.0/runs` remain supported for
compatibility. Details live on each guide page.

First, create an avatar from a prompt, reference photo, or supported avatar
input. Avatar creation is job-backed, so Sume returns a job first. When the job
finishes, the avatar becomes a reusable resource in your workspace.

Use a stable avatar handle when possible. That gives your app or agent a simple
name to reuse later instead of relying only on a generated id.

After the avatar is ready, send a script (or `video_inputs`) and the avatar
handle to create an avatar video. Each video is also job-backed: submit the
request, poll or wait for completion, then read the result URL.

Avatar Video supports `quality: "standard" | "plus" | "max"`. Omit it for the
default **`plus`** execution path. Use `standard` for the fastest path and
`max` when quality matters more than turnaround.

### Related Avatar utilities

| Guide | Use for |
|---|---|
| [Create your avatar](/models/avatar) | Avatar creation request. |
| [Generate avatar video](/models/avatar-videos) | Talking video from a ready avatar. |
| [Avatar video previews](/models/avatar-video-previews) | First-frame stills before a full render; then `generate-video`. |
| [Face swap (Beta)](/models/face-swap) | Swap a ready avatar face onto a public source video. |
| [Video captions](/models/video-captions) | Burn captions onto an existing public video URL. |
| [Video inspect](/models/video-inspect) | Probe + stills + optional STT of one `media.sume.com` clip. Default clip inspection on dest and prod. |
| [Reference ingest](/models/reference-ingest) | One reference clip → `ReferenceVideoManifest` (frame-exact shots, source-resolution OCR text tracks, audio facts, labeled strip). Unbilled; dest first. |
| [Video frames](/models/video-frames) | Exact stills at `at[]` / `fps` from one hosted clip. Source-size `artf_` images. Unbilled. Always `202`. |
| [Video trim](/models/video-trim) | `[start, end)` of one hosted clip → new MP4. `$0.02` flat. Material for timeline, not placement. |
| [Audio detach](/models/audio-detach) | Audio track of one hosted video → durable wav / mp3. `$0.01` flat. |
| [Video filter](/models/video-filter) | Dim / crop / allowlisted pixel graph on one hosted clip → new MP4. `$0.02` encode; `/check` is free. |
| [Timeline 1.0](/models/timeline) | Audio spine + ordered `video[]` → one MP4. `$0.10` / ceil(output minute). The assembly surface. |
| [Timeline compose](/models/timeline-compose) | Still + video in one frame (반배너 / overlay) → one MP4 shot. `$0.02` flat. |
| [Timeline audio](/models/timeline-audio) | Concat / split Sume-hosted audio → durable files. `$0.01` flat. |
| [Video analyses](/models/video-analyses) | Legacy `vana_` resource. Dest create is `410`; prod still accepts until #5953 PR-C2. |
| [Trending videos](/models/trending-videos) | Discover TikTok trending video metadata for research. |

## Image, Video, Music, Fabric

Managed product models — Sume selects providers; callers do not send provider
queue ids. VEED Fabric 1.0 is public as `veed/fabric-1.0`.

| Family | Primary URL | Guide |
|---|---|---|
| Image 1.0 | `POST /v1/image-1.0/generate` | [Image 1.0](/models/image) |
| Image API | `POST /v1/images` | [Image API](/models/images) |
| Video 1.0 | `POST /v1/video-1.0/generate` | [Video 1.0](/models/video) |
| Video generation | `POST /v1/videos` | [Video generation](/models/videos) |
| Music Router | `POST /v1/music-router/generate` | [Music Router](/models/music-router) |
| Music 1.0 (retiring; resolves through Music Router) | `POST /v1/music-1.0/generate` | [Music 1.0](/models/music) |
| VEED Fabric 1.0 | `POST /v1/veed/fabric-1.0` | Talking still + audio clips (`veed/fabric-1.0`) |

### Fabric alias migration

**Deprecated / retiring compatibility aliases — still supported:**

| Deprecated route | Correct call |
|---|---|
| `POST /v1/avatar-1.0/image-to-video` | `POST /v1/veed/fabric-1.0` |
| `POST /v1/models/sume/avatar-1.0/image-to-video/runs` | `POST /v1/models/veed/fabric-1.0/runs` (or `POST /v1/veed/fabric-1.0`) |

The public model id is `veed/fabric-1.0`. Both aliases keep accepting the same
body, so existing Mobidoo / live-commerce integrations can migrate by changing
only the URL. Send `audio_url`, measured `duration_seconds`, and exactly one visual
source. Prefer `image_url` of the generated, inspected posed still; use
`avatar_handle` instead only when the user named that avatar. They are mutually
exclusive. With MCP, the same body lives inside `payload` on the supported
`avatar-image-to-video_create` tool.

Every on-camera speaking shot is Fabric with an accepted still + TTS: short UGC
and presenter ads, testimonials, Recreate speaking beats and LC / long-form host
talk alike. Video models do not lip-sync to generated TTS or to a later
voice-over, so a talking face is never a video-model clip with narration laid
underneath. Wordless beats, B-roll and product motion use Auto image → inspect
→ Auto video, without Fabric or Stage P.

Model-run aliases use `POST /v1/models/sume/<family>/runs` (same request body)
for Image 1.0 / Video 1.0 / Music 1.0.

Prefer Image 1.0 / Video 1.0 + `routing_preset` unless you need an explicit
catalog model id (for example Seedance). Pin that id on
[Video generation](/models/videos) (`POST /v1/videos`) or
[Image API](/models/images) (`POST /v1/images`). Legacy
`/v1/video-router/*` stays registered as a Sume-envelope alias — see
[Video Router](/models/video-router).

## Shared job lifecycle

These families return the same job envelope pattern:

1. Submit → store `job.id`, `status_url`, `result_url`.
2. Poll status (or wait with `mode: sync` / `subscribe` up to 30s).
3. Fetch `/result` when `result_ready` is true.
4. Read Sume-hosted `artifacts` for media jobs.

See [Jobs and results](/workflows/jobs-and-results),
[Generation admission](/workflows/generation-admission),
[Media inputs](/workflows/asset-library), and [API recipes](/api/cookbook).

## Ahead of production OpenAPI

Some additional generators (for example STT) may appear on `api.dev.sume.com`
before they are listed in the production OpenAPI snapshot. Do not treat those
paths as production Developer API surface until they land in the docs OpenAPI
snapshot and `api.sume.com` reference.

### Experimental: `POST /v1/avatar-1.0/fabric`

`sume/avatar-1.0/fabric` is a **temporary, test-only** route used to compare a
different talking-clip backend against
`POST /v1/veed/fabric-1.0` (legacy `POST /v1/avatar-1.0/image-to-video`) on
identical inputs. It takes the same
request body so a comparison script only has to swap the path.

Differences from `image-to-video`:

| | `image-to-video` | `fabric` (experimental) |
|---|---|---|
| `duration_seconds` | 1–300 | 1–15 (rounded up; requests over 15 are rejected) |
| `speed_tier` | selects a provider speed tier | accepted and ignored |
| Price | $0.165/s @720p | $0.267/s @720p |

Do not build production integrations on this route:

- The name `fabric` is placeholder test branding and **will change before
  general availability**.
- The route may be changed or removed outright once the comparison is done.
- VEED Fabric 1.0 (`veed/fabric-1.0`) stays the supported path for talking
  clips, including Live Commerce and the MCP tools.