Call a Sume catalog Format without forking it: the sume handle

You do not need to fork, install or copy a Sume catalog Format. Read it with GET /v1/formats/sume/{slug}, check its io profile, and call POST /v1/formats/sume/{slug}/runs with a key that has formats:write. The run, its media and its spend belong to your key. Fork only when you need to change the recipe.

Read before you call

Two fields on the Format describe what it takes and what it makes. io.input_kind is one of url, text, image or product. io.output_kind is one of video, image or text. showcase is a real output from a registration run, checked against the generated-media ledger before it is stored.

Both fields are null for Formats saved before registration existed. That means not declared, not takes nothing. Then use the Format's description.

curl -sS "https://api.sume.com/v1/formats/sume/sume-before-after" \
  -H "Authorization: Bearer $SUME_API_KEY"

Pick a slug

The catalog answers 27 slugs today, including sume-product-commercial, sume-video-hook, sume-slideshow, sume-green-screen, sume-recreate and sume-restyle. Any slug not on the list returns 404 format_not_found at sume/{slug}.

• Product ads: sume-product-commercial, sume-product-usage-demo, sume-before-after.
• Short hooks and talking formats: sume-video-hook, sume-green-screen, sume-wall-of-text.
• Beauty product motion: sume-serum-drip, sume-toner-pour, sume-cream-squeeze.

Call it

The wire contract is the same as for your own Formats: an Idempotency-Key, a body with at least one of instruction, input, previous_run_id or attachments, and optional spend cap and webhook.

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: commercial-sku-8823-v1" \
  -d '{
    "instruction": "Vertical 9:16 product commercial, no captions.",
    "input": { "product_name": "Aurora Headphones" },
    "generation_spend_cap_usd": 60
  }'

Read the receipt that comes back

A fresh run answers 202 with a receipt. A replay of the same key and body answers 200 with idempotency_hit: true. In both cases format.id is the opaque skl_... id, whichever address you used. The receipt holds its own status_url, result_url, events_url and cancel_url, and the docs ask you to use those URLs rather than build the paths yourself.

Store data.id and poll status_url with a back-off, or send a webhook. The poll payload is small: status, next_action, cancelable, expires_at and timestamps. The full receipt with primary_output_url comes from result_url once the run is terminal. Before that, result_url returns 409 run_not_completed.

• Renamed handles continue to resolve for 90 days, so a stored URL does not break the day a team renames its handle.
• Use {format_id} addresses when a stored URL must outlive a rename for good.
• Service-account keys cannot create Format runs and get 403 insufficient_scope.

When to fork

A catalog Format stays shared and unowned, so you cannot edit it. To change it, fork it in the Format library. Then the address of your copy is {your_handle}/{slug}, and you call it the same way.

If your copy belongs to a team workspace, use a key created in that workspace. A personal key gets 403 workspace_key_required.