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.
Related Avatar utilities
| 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 inspect | Probe + stills + optional STT of one media.sume.com clip. Default clip inspection on dest and prod. |
| Reference ingest | One reference clip → ReferenceVideoManifest (frame-exact shots, source-resolution OCR text tracks, audio facts, labeled strip). Unbilled; dest first. |
| Video frames | Exact stills at at[] / fps from one hosted clip. Source-size artf_ images. Unbilled. Always 202. |
| Video trim | [start, end) of one hosted clip → new MP4. $0.02 flat. Material for timeline, not placement. |
| Audio detach | Audio track of one hosted video → durable wav / mp3. $0.01 flat. |
| Video filter | Dim / crop / allowlisted pixel graph on one hosted clip → new MP4. $0.02 encode; /check is free. |
| Timeline 1.0 | Audio spine + ordered video[] → one MP4. $0.10 / ceil(output minute). The assembly surface. |
| Timeline compose | Still + video in one frame (반배너 / overlay) → one MP4 shot. $0.02 flat. |
| Timeline audio | Concat / split Sume-hosted audio → durable files. $0.01 flat. |
| Video analyses | Legacy vana_ resource. Dest create is 410; prod still accepts until #5953 PR-C2. |
| 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 |
| Image API | POST /v1/images | Image API |
| Video 1.0 | POST /v1/video-1.0/generate | Video 1.0 |
| Video generation | POST /v1/videos | Video generation |
| Music Router | POST /v1/music-router/generate | Music Router |
| Music 1.0 (retiring; resolves through Music Router) | 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) |
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 (POST /v1/videos) or
Image API (POST /v1/images). Legacy
/v1/video-router/* stays registered as a Sume-envelope alias — see
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/subscribeup to 30s). - Fetch
/resultwhenresult_readyis true. - Read Sume-hosted
artifactsfor 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
fabricis 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.