Format API: webhook or polling for a run that takes 15-30 minutes

For a Sume Format run that makes video, plan on minutes, not seconds: the docs say long-form host video usually completes in 15 to 30 minutes. Start the run with POST /v1/formats/{handle}/{slug}/runs, which returns 202 and a receipt. Then take the result by webhook, a signed format.run.terminal POST, or poll GET /v1/format-runs/{run_id}. There is no SSE or WebSocket progress stream.

What the receipt gives you

A 202 means Sume accepted a fresh run. Store data.id (arun_...). The receipt includes ready-made URLs, so you never build a path by hand.

Webhook or poll

Set communication.webhook_url on the create call and Sume POSTs the same receipt once, as one signed format.run.terminal event, when the run ends. Verify the signature using the scheme in the webhooks guide, and refuse to run a verifier with an empty secret. To poll instead, read the run until status is terminal. A run never delivers partial results: it is completed or failed.

With a 15 to 30 minute run, polling every 30 seconds is 30 to 60 requests; a webhook is one. Use a webhook as the primary path and a slow poll as a backstop.

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: order-8823-v1" \
  -d '{
    "instruction": "Vertical 9:16 host video, no BGM.",
    "input": { "product_url": "https://shop.example.com/p/8823" },
    "generation_spend_cap_usd": 120,
    "communication": { "webhook_url": "https://acme.example.com/hooks/sume" }
  }'

Retries and failures

Use an Idempotency-Key on the create call so a retry after a timeout does not start a second run. A key replayed after a failed create (402, 503) is released, so correct the cause and retry with the same key. A run that could not finish comes back as failed; it never delivers partial results. If you need to stop a run, cancel_url is on the receipt.

On the host side, https://api.dev.sume.com accepts the same routes and receipts for integration work, with keys issued separately; a key works only on the host that created it.

Choosing a poll interval

If you poll, 30 seconds is a reasonable interval for a run measured in tens of minutes. The events_url timeline shows only the three phases, preparing, running, and finalizing, so it tells you roughly where a run is, not what the agent is doing. For a human watching progress, the run's thread_id opens the conversation in Agents, where the first message is the exact text the agent received. Read that first when a run did something you did not expect.

Reading the finished run

When complete, primary_output_url is the file to show, and artifacts[] lists everything the run made, as durable media.sume.com URLs. If you bound an output schema, output comes back in your shape. The receipt also reports usage.billable_amount_usd_micros against the cap. A Format run is one unattended turn that does not stop to ask questions, so design your integration around the asynchronous path from the start.