Avatar video previews: approve the first frame before rendering

An avatar video preview is the first-frame still stage of a Sume talking-avatar video, generated without starting the full render. Create one with POST /v1/avatar-video-previews, review or regenerate the stills, then call generate-video on the preview id to start the final render.

Every detail below comes from the Avatar video previews docs page.

When should I use a preview?

Use a preview when you want to approve composition before spending a full Avatar Video generation. For a direct full render without the preview stage, use Generate avatar video instead, as shown in Talking avatar video API. Previews fit three cases:

• Reviewing scene framing and first frames before a full render.
• Multi-scene video_inputs where you want one still per scene. See Multi-scene avatar video API.
• Storing caption intent on create, then applying captions only at generate-video time. Preview stills are never caption-burned.

Which endpoints make up the preview flow?

How do I create a preview?

The create body matches Avatar Video fields: 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, or max).

Poll the returned job like any other generation, at /v1/jobs/job_123/status and /v1/jobs/job_123/result.

curl -X POST https://api.sume.com/v1/avatar-video-previews \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "avatar_handle": "product_host",
    "script": "Meet the Acme travel mug. It fits every cup holder and every bag.",
    "quality": "plus"
  }'

What does a ready preview contain?

Read the preview resource by id. When ready, its public-safe fields include:

• preview_image_url: the primary still (scene 0 for multi-scene).
• scene_previews[]: one still per input scene, when available. For multi-scene previews with a shared scene, later scene stills are pose-anchored continuations of the first frame.
• resource_status / job_status: prefer these over the legacy status field for readiness vs job polling.

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

How do I regenerate the stills?

Call POST /v1/avatar-video-previews/:id/regenerate. It reuses the stored preview request (avatar, script or video_inputs, scene, quality, aspect ratio) and only refreshes the first-frame stills. It returns the same avatar_video_preview_id with a new preview-only job.

How do I turn an approved preview into the final video?

Call generate-video on the preview id. Sume starts the normal Avatar Video workflow and reuses the preview first frame when available. Captions stored on preview create apply at this step. Poll the returned job, then read the avatar-video resource at /v1/avatar-videos/avatar_video_123.

The final render is a full Avatar Video generation, priced per second by tier at $0.184/s standard, $0.245/s plus, $0.55/s max (no product image), with the default 5.5% agent fee on top. Rates with a product image are on API pricing.

• An empty body, or {}, keeps the quality chosen at preview create.
• An optional quality overrides the final render tier only. Preview stills are tier-independent and always reused, so approving and then switching tier does not require a new preview.
• Admission, pre-spend, ledger reservation, provider submit, and readback all use the effective (overridden) tier.
• Changing a structural field (script, video_inputs, avatar_handle, scene, or aspect_ratio) still requires a new preview.

curl -X POST https://api.sume.com/v1/avatar-video-previews/avp_123/generate-video \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "quality": "standard" }'

What limits apply to previews?

• 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.
• generate-video quality only changes the final video provider tier.
• Exact request and response schemas are in the live OpenAPI.