Product promo

The job: hand it a product or brand URL and a short brief, get back ad images or a promo video. The Format decides the branch — talking-head UGC or product-motion image-to-video — pulls real product imagery from the URL rather than inventing it, and carries the house style so you do not restate it on every call.

Use it when the task is the same each time and only the product changes. If the task itself varies per call, use Agent Completions instead.

First-party slug: sume-product-promo.

1. Address it

Call it at sume/sume-product-promo with any key that carries the scopes below. Nothing to fork, nothing to install: the catalog Format is shared and unowned, and the run, its media and its spend belong to the key that called.

Forking is still available when you want to change the Format — open Product promo in the Format library and press Fork for an editable copy owned by you. The fork keeps the body and the spend cap, and takes a new slug (the dashboard suggests sume-product-promo-custom, since a fork must not reuse its source's slug); its detail page shows it as {your_handle}/{slug}. That is a customization step, not a prerequisite for calling.

2. Scopes

ScopeNeeded for
formats:readRead the Format, read and list its runs.
formats:writeStart a run, cancel a run.

Keys created before Formats shipped do not carry these, and scopes cannot be added to an existing key — mint a new one at API Keys and rotate to it. Service-account keys cannot start Format runs.

3. Call it

The opaque skl_… path stays valid for clients that already store it; new integrations should use {handle}/{slug}.

An accepted run returns 202:

Send Idempotency-Key on every call. A replay with the same body returns 200 and the original run; a replay with a different body returns 409 idempotency_conflict.

input

input is free-form JSON, fenced into the prompt as caller data and never as instructions — concatenated, not validated against a wire schema. Use whatever shape is convenient for your backend; the Format body decides which keys it reads. The example above is a realistic shape, not a contract. Keep it small and literal: at most 64 keys and 8 KiB.

Anything that is a decision belongs in instruction. Anything that is data belongs in input. More on composition: Calling a Format.

4. Spend cap

Promo runs generate paid media, so the cap is the control that matters.

The Format's cap is what a run inherits when it names none. Read the current value from PublicFormat.generation_spend_cap_usd_micros. A Format that never named one gets the platform default of $400; the ceiling you can set is $500.

generation_spend_cap_usd on a run names that run's own ceiling, up to $500 — above the Format's own cap is honored, above $500 is an error. Omit it and the run gets the Format's cap.

5. Poll, then read the result

Statuses are queued, processing, completed, failed, canceled, skipped. Poll status_url for the cheap check; it returns just the status fields and next_action.

A completed receipt carries output, artifacts[] — every durable file the run produced — and primary_output_url. Media URLs are durable media.sume.com HTTPS URLs and do not expire.

Cancel a run in flight:

Cancel is a no-op once the run is terminal; the current receipt comes back either way.

Two things that surprise people

A fresh fork reads as inactive until its first run. GET /v1/formats/{format_id} reports status: "inactive" and api_trigger_enabled: false on a copy you just made, because both are read off a runner that is provisioned lazily. Do not gate your integration on those fields being true — the first POST .../runs provisions the runner and the run proceeds normally. sume/{slug} itself always reads active, since the catalog is callable by definition.

API runs are unattended. The Format body was written for chat, where it can stop and ask a person to approve preview stills before the paid step. Over the API nobody is there, so the run is told those approvals are already granted and to carry on within the spend cap. A run that genuinely cannot finish comes back failed with output_error.code of unattended_blocked — never a half-finished completed.

Next