Live-commerce host video by API: instruction, input, schema, webhook
How a Sume Format run for a live-commerce style host video is shaped: instruction for decisions, input for data, an output schema, a spend cap and a webhook.
A live-commerce host video on Sume is one Format run: POST /v1/formats/{handle}/{slug}/runs with an instruction for decisions, an input object for data (product URL, host image, voice language, script), an optional output_schema, a generation_spend_cap_usd and a communication.webhook_url. You get a 202 receipt, then one signed format.run.terminal event when it ends. The Format docs say long-form host video typically takes 15 to 30 minutes, so build it asynchronously from day one.
Everything here comes from the Format cookbook and Calling a Format; handles and URLs are placeholders.
What goes where
The cookbook is explicit about the split. Decisions go in prose, data goes in structured keys, and your own bookkeeping can ride along in input but will not come back in output.
| Key | Why it is there |
|---|---|
instruction | Use the script as written; framing; what not to add. Prose, well under 4000 characters |
input | product_url, host_image_url, vo_language, script, price; unknown keys ride along as context |
output_schema | Names the assembled cut and each scene so you can retry a scene by id |
primary_output_key | Makes primary_output_url the assembled cut and fails a run that lacks it |
generation_spend_cap_usd | The ceiling for this run |
communication.webhook_url | One signed POST when the run ends; result_url stays as a backup |
A minimal request
Keep the real body in a file, because long scripts are awkward in a shell heredoc. The shape below is trimmed.
curl -sS -X POST "https://api.sume.com/v1/formats/acme/live-commerce/runs" \
-H "Authorization: Bearer $SUME_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: sheet-45-v1" \
-d @run-body.jsonAfter the receipt
Store data.id and data.thread_id: the first for the receipt, the second to group retries. When the webhook arrives, branch on outcome: ok has your output, degraded has real media but a null output, and error did not complete. A scene marked failed can be retried with previous_run_id while the voice track and other clips stay as they were.
- Verify the signature before you parse.
- Dedupe on
request_id. - Fetch
result_urlwhenpayloadis null (receipts over 1 MiB). - Keep one slow poll as a backup.
What this is not
A Format run is not a live stream. It produces a finished video you can publish or cut into a broadcast, and it does not host a viewer chat or take orders. Treat the output as one input to your commerce stack.
Sources
Related posts
More in Use cases
- Lofi study stream: a 30-second track looped as a Sume soundtrack
A lo-fi study stream needs a bed that repeats cleanly. Generate a 30-second track with Sume's router and loop it under a video with soundtrack.loop.
- Lyria 3.5 screens prompts: brand slogans and lyrics in an ad song
Google says every Lyria prompt is safety-screened and it cannot output copyrighted lyrics or named artist voices. How to write a brand jingle brief that passes.
- Make 3-minute hold music for a voice agent
ElevenLabs agents can play hold audio up to 180 s and 40 MB. Generate a short loop with Sume music generation and join it into 180 s with timeline audio.
- Meta ad video length by placement: 15 s to 240 min
Meta's placement chart sets different lengths and ratios per placement, from 15 s Messenger Stories to 240 min Feed. A render plan by placement.
Written by Sume