Calling a Formats by Sume entry: the sume handle, not yours

A ready-made Format by Sume is called at the reserved sume handle: POST /v1/formats/sume/{slug}/runs. Any key carrying formats:write may call it, the run and its spend belong to your key, and the catalog entry itself stays shared and unowned. Addressing one at your own account handle returns 404 format_not_found.

This comes from the Formats by Sume page, with the 404 case named in the Embed a Format cookbook.

Which address do I use?

Three address shapes exist for a Format, per the Create a run page.

Whose run is it?

Yours. The page says the run, its media and its spend belong to the calling key, while the catalog Format stays shared. There is nothing to fork, install or copy first, which makes a catalog Format the shortest path from an API key to a finished video.

The wire contract is unchanged: same body, Idempotency-Key, spend cap and receipt as any Format. The receipt's format.id is still the opaque skl_... id.

When should I fork instead?

Fork a catalog Format in the Format library when you want to change it. Your copy is then addressed as {your_handle}/{slug}, and Formats you author yourself are called exactly the same way.

If a call that used to work at sume/{slug} now 404s, check the slug first, then the handle: a slug you forked is yours, and the catalog one stays at sume.

How do I find the right slug and input?

GET /v1/formats lists the Formats your key can call, including the catalog, with io.profile, input_kind and output_kind. The docs say input is a free-form object by design, so this profile and the Format's description are the only declared contract between author and caller.

Both io and showcase can be null for Formats saved before registration existed, which means "not declared", not "takes no input".

What does a first call look like?

The create body is the same as for your own Format: at least one of instruction, input, previous_run_id or attachments, plus an Idempotency-Key. This example uses a slug the docs show; list the catalog first, since slugs are the catalog's to change.

The usual create errors apply. A key without formats:write is 403 insufficient_scope, an empty wallet is 402 insufficient_credits, and a body naming none of the four fields is 400 invalid_request. A 202 returns a receipt with status_url, result_url, events_url and cancel_url; follow those rather than building paths.

For long runs, pass communication.webhook_url and keep polling result_url as the backup.

curl -sS -X POST "https://api.sume.com/v1/formats/sume/sume-product-commercial/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8823-commercial-v1" \
  -d '{"input": {"product_url": "https://shop.example.com/p/8823"}}'