Approve the first frame, then pick the tier: Avatar video preview

To approve an avatar ad before you pay for the render, create an Avatar video preview, review the first-frame stills, regenerate if needed, and call generate-video on the preview id. You can set the render quality at that last step, so you can approve the look at one tier and render at another.

This is the cheap way to run a holiday batch. A look problem, such as a wrong room, a cropped product or a stiff pose, shows up in a still. You find it before the talking video exists.

The four routes

The preview docs list four routes. The create body has the same fields as Avatar Video: script or video_inputs (not both), plus optional product_image, scene, quality, aspect_ratio, title and captions.

What the preview shows

A multi-scene preview gives one still per scene in scene_previews[]. When scenes share a scene, later stills are pose-anchored continuations of the first frame, so you review one look, not five.

Captions are stored at create time but never burned into stills. They apply only at generate-video, so you will not see them in the preview. Judge captions on the final render, or on a cheap standard-tier test.

Prefer resource_status and job_status over the legacy status field when you poll. The first tells you whether the preview resource is ready, and the second tells you about the job.

Approve once, render at any tier

An empty body, or {}, keeps the quality you chose at preview create. An optional quality overrides only the final render tier. The docs say preview stills are tier-independent and Sume always reuses them, so approving at one tier and rendering at another needs no new preview.

That gives a workflow with two spend levels. Create previews cheaply, approve the look, render the candidate at standard ($0.184 per second without a product, per the Sume rate table), and re-render the one that wins at plus ($0.245) or max ($0.55). For a 12-second ad that is $2.21, $2.94 and $6.60.

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" \
  -H "Idempotency-Key: avp-123-final" \
  -d '{"quality": "max"}'

What forces a new preview

Admission, pre-spend, ledger reservation, provider submit and readback all use the effective tier, so the override is real, not cosmetic. The docs call this out, and it means your budget check should use the tier you pass at generate-video, not the one on the preview.

Changing script, video_inputs, avatar_handle, scene or aspect_ratio still needs a new preview. If the legal team edits one line of the script after approval, create a fresh preview, since the stored stills were built for the old plan.

I have not found a preview price in the docs, so check your usage reads or the pricing page before you plan a large batch around previews.

A holiday batch

For a ten-variant holiday test: create ten previews, review the stills as a contact sheet, drop the weak looks, and render the survivors. Poll each job with GET /v1/jobs/{id}/status and read GET /v1/jobs/{id}/result when it is complete. Keep the preview id next to the variant name in your sheet, since it is the handle for both regeneration and the final render.

Approve, regenerate or restart

Think of the preview as a gate with three outcomes: approve, regenerate or restart. Approve means you call generate-video. Regenerate means the stored request is fine and only the stills need another try, for example because the lighting or the pose is off. Restart means the request itself is wrong, such as a script change or a different aspect ratio, and you create a new preview.

Regenerate is the useful one for a batch. It reuses the stored avatar, script, scene, quality and aspect ratio, and returns the same avatar_video_preview_id with a new preview-only job. You never lose the handle you put in your sheet.

Because stills are tier-independent, there is no reason to preview at a high tier. Keep the preview at the default and put the higher tier on the final render only if the clip earns it. Many holiday ads that run for a weekend do not.