AI avatar video with your product and background via API

To put your product and a background into a Sume Avatar 1.0 talking video, add product_image (a public HTTPS image URL) and scene (a text prompt or a photo URL) to POST /v1/avatar-1.0/talking-video. Both fields are optional. To see how they come out before paying for the full render, create an avatar video preview with the same fields first.

The field rules come from Sume's Generate avatar video, Media inputs, and Avatar video previews docs and the API reference, read on 2026-09-26. The basic script request is in Talking avatar video API.

Which fields add a product and a background?

A single-script video takes product_image and one scene. A multi-scene video_inputs plan can also give each scene a background, but current execution expects every scene background to resolve to one shared scene.

What does a product request look like?

This follows the docs example, with a placeholder handle and a new script:

curl -X POST https://api.sume.com/v1/avatar-1.0/talking-video \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: avatar-product-001" \
  -d '{
    "avatar_handle": "product_host",
    "script": "Meet the Acme travel mug, now in three colors.",
    "product_image": "https://example.com/product.png",
    "scene": { "type": "prompt", "prompt": "Bright studio with clean product table" },
    "quality": "plus",
    "aspect_ratio": "9:16"
  }'

Will the avatar hold the product?

The docs do not say. They describe product_image as an optional product/reference image and say nothing about where or how the product appears in frame. The way to find out for your product is to look at the first frame in a preview, before the full render bills.

Which image URLs are accepted?

Media fields must be fetchable public HTTPS URLs, and you do not need to create a separate Sume asset first. These are rejected before generation is submitted:

• Localhost and private-network URLs.
• Non-HTTPS URLs and signed or private URLs.
• Responses whose content type does not match, such as a non-image response for product_image or scene.image_url.

How do I check the product and background before paying?

Create a preview with POST /v1/avatar-video-previews. Its body matches the Avatar Video fields, including product_image and scene. When ready, preview_image_url is the primary still and scene_previews[] holds one still per input scene when available. Avatar video previews covers the flow in full.

• POST /v1/avatar-video-previews/:id/regenerate reuses the stored request and only refreshes the first-frame stills.
• POST /v1/avatar-video-previews/:id/generate-video starts the render from the approved preview and accepts only a quality override, so a different product_image or scene means a new preview.

What does a product add to the price?

A product image moves the video to the "with product" rate of its tier, each plus a 5.5% agent fee by default: