Models overview

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 (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:

Create a reusable avatar.
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.

Guide	Use for
Create your avatar	Avatar creation request.
Generate avatar video	Talking video from a ready avatar.
Avatar video previews	First-frame stills before a full render; then `generate-video`.
Face swap (Beta)	Swap a ready avatar face onto a public source video.
Video captions	Burn captions onto an existing public video URL.
Video analyses	Scene-by-scene understanding of an existing public video URL.
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
Video 1.0	`POST /v1/video-1.0/generate`	Video 1.0
Video Router	`POST /v1/video-router/generate`	Video Router
Music 1.0	`POST /v1/music-1.0/generate`	Music 1.0
VEED Fabric 1.0	`POST /v1/veed/fabric-1.0`	Talking still + audio clips (`veed/fabric-1.0`)

Model-run aliases use POST /v1/models/sume/<family>/runs (same request body) for Image / Video / Music. Video Router uses its own catalog paths.

Prefer Video 1.0 + routing_preset unless you need an explicit catalog model id (for example Seedance) via Video Router.

Shared job lifecycle

These families return the same job envelope pattern:

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

See Jobs and results, Generation admission, Media inputs, and API recipes.

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.

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