Avatar video previews

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.

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.

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

Create an avatar-video preview

POST /v1/avatar-video-previews

Required

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

Read the preview resource

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:

Regenerate preview stills

POST /v1/avatar-video-previews/{id}/regenerate

Required

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.

Generate video from preview

POST /v1/avatar-video-previews/{id}/generate-video

Required

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:

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.