AI UGC ad generator API: two ways to make UGC-style ads with Sume

To make a UGC-style ad video with the Sume API, either call a catalog Format such as sume-close-camera-ugc at POST /v1/formats/sume/{slug}/runs with your brief in instruction and product images in attachments, or render an Avatar 1.0 talking video at POST /v1/avatar-1.0/talking-video with your own script, a product_image, and a scene.

The facts below come from Sume's Format catalog, Create a run, and Generate avatar video docs pages, read on 2026-09-26. The whole catalog is covered in Ready-made Formats for product video.

Which catalog Formats fit a UGC-style ad?

The catalog answers at the reserved sume handle. Two of its slugs end in ugc, and a third names a product usage demo. What a Format does is its own saved recipe, so read one before you call it: GET /v1/formats/sume/{slug} returns its description and its io profile, whose input_kind tells you what shape of input it expects. Any slug not in the catalog answers 404 format_not_found.

How do I call a UGC Format?

A catalog Format is called like any Format, with a key that has formats:write; the catalog-wide rules are in Ready-made Formats for product video. For a UGC-style ad, put the brief in instruction and product shots in attachments, up to 30 images the agent can see. Media URLs you place in input instead share one budget with attachments: 30 files per run, at most 10 of them videos and 10 audio. The agent applies the Format's recipe, and the Format's tools choose the image, video, and audio models.

Send an Idempotency-Key on every create. A 202 returns the run receipt; add communication.webhook_url to receive one signed format.run.terminal POST when the run completes or fails.

curl -sS -X POST "https://api.sume.com/v1/formats/sume/sume-close-camera-ugc/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sku-4411-ugc-v1" \
  -d '{
    "instruction": "Short vertical ad for the attached product.",
    "attachments": [
      { "type": "input_image", "image_url": "https://example.com/product.jpg" }
    ],
    "generation_spend_cap_usd": 20
  }'

How do I make a UGC-style ad with an avatar instead?

Use the avatar path when you want to choose the presenter and write every word. The request names a ready avatar with avatar_handle and exactly one of script or video_inputs. Omit product_image for a productless video. scene can be { "type": "prompt" } with a prompt or { "type": "photo" } with an image_url, and media fields must be fetchable public HTTPS URLs. No avatar yet? See how to create a reusable AI avatar.

The docs' multi-scene example is shaped like a UGC ad: a spoken hook, a four-second silence beat named demo, and a spoken call to action, each with the background prompt "Casual bedroom framing, native UGC lighting".

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: ugc-avatar-sku-4411-v1" \
  -d '{
    "avatar_handle": "acme_host",
    "script": "I kept this in my bag all week. Here is why.",
    "product_image": "https://example.com/product.png",
    "scene": { "type": "prompt", "prompt": "Casual bedroom framing, native UGC lighting" },
    "quality": "plus",
    "aspect_ratio": "9:16"
  }'

Can I add captions and check the first frame before paying?

Yes, on the avatar path. Optional captions burns a style into the final MP4 from the spoken script; slam is the default style, and inline captions do not create a separate billed caption job. If the caption stage fails, the avatar job can still succeed with a clean video_url and captions.status=failed. To review first-frame stills before paying for a full render, create an avatar video preview and call generate-video on its id, as in avatar video previews.

Which path should I choose, and what does it cost?

Pick a catalog Format when you want its saved recipe and tools to make the production choices, and the avatar route when you need a set presenter and exact words. On the Format path, generation that counts against the run's cap is metered at the API pricing rates, and generation_spend_cap_usd bounds it: up to $500, null runs at $500, and 0 is rejected. The receipt's usage.billable_amount_usd_micros excludes the agent's own LLM turn, so it is not the run's total cost. An avatar video is priced per second by quality and by whether you send a product image. With a product image the rate is $0.194 per second for standard, $0.258 per second for plus, and $0.58 per second for max.

What are the limits?

These bounds come from the same docs pages:

• Avatar scripts and multi-scene plans must land at an estimated 4–60 seconds. Shorten a longer script or split it into several jobs.
• Current avatar execution supports one resolved avatar per final video and expects scene backgrounds to resolve to one shared scene.
• Avatar aspect_ratio is 1:1, 3:4, 9:16, 4:3, or 16:9; resolution is currently 720p.
• A catalog Format is used as published. To change one, fork it in the Format library and call your copy at {your_handle}/{slug}.