Sume Format bulk runs: queue up to 100 renders in one request

A Sume Format bulk run is a server-side queue of ordinary Format runs: one POST …/bulk-runs request carries up to 100 items, each the same body as a single run and each still one sandbox, one agent turn, and one run receipt. Sume keeps concurrency of them (1–16) in flight until the list is drained.

The details below come from Sume's Bulk runs and Create a run docs pages, read on 2026-09-25.

How do I create a bulk queue?

Send POST /v1/formats/{handle}/{slug}/bulk-runs with an API key that has formats:write. The opaque twin, POST /v1/formats/{format_id}/bulk-runs, takes the same body and returns the same receipt. An accepted create answers 202 with a format.run_queue object. If a single Format run is new to you, start with What is a Sume Format?

• concurrency: required integer, 1–16. How many child runs stay in flight at once.
• items: required array of 1–100 entries, in order. Each entry is a normal run body, so it can carry its own output_schema, generation_spend_cap_usd, and communication.webhook_url.
• Each item must name at least one of instruction, input, previous_run_id, or attachments. One bad item fails the create with 400 invalid_request and details.index, before a queue exists.
• Unknown top-level fields are rejected, and { "concurrency": 3 } without items is a 400, not an empty queue.

curl -sS -X POST "https://api.sume.com/v1/formats/acme/product-promo/bulk-runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: spring-catalog-batch-1" \
  -d '{
    "concurrency": 3,
    "items": [
      { "instruction": "clip 1", "input": { "url": "https://example.com/1.jpg" } },
      { "instruction": "clip 2", "input": { "url": "https://example.com/2.jpg" } },
      { "instruction": "clip 3", "input": { "url": "https://example.com/3.jpg" } },
      { "instruction": "clip 4", "input": { "url": "https://example.com/4.jpg" } }
    ]
  }'

How does the concurrency window work?

The server drives the fan-out, not your client. Create already fills the window: with concurrency: 3 and 8 items, the 202 receipt shows three running and five queued. When a child completes, fails, or is canceled, its slot frees and the next queued item starts immediately. The window never exceeds concurrency.

Children still go through ordinary Format-run admission: wallet, workspace generation concurrency, and spend caps. A child that fails to start becomes a failed item and the window refills from the remaining queued items; the create has already returned 202. Every item runs with on_active_run: "allow", so skip or reject on an item does not stall the window.

How do I track a queue's progress?

Poll the queue's status_url, GET /v1/format-run-queues/{queue_id}, with a key that has formats:read. It returns the same object as the create: a queue status, counts (total, queued, running, completed, failed, canceled), and one items row per submitted item with its index, status, run_id, and error.

• Queue completed means every item is terminal, not that all succeeded. Branch on counts.failed and counts.canceled.
• When a child run fails or is canceled, its item's error is just format_run_failed or format_run_canceled. Read why on the child's own receipt at GET /v1/format-runs/{run_id}.
• Back off between polls. Each child is minutes of work when the Format makes video, and polling spends the read budget. A 429 or 503 while polling is transient; the queue keeps working.

Is there a webhook for the whole batch?

No. The queue object has no webhook, and there is no queue-level callback. Set communication.webhook_url on each item and every child that completes or fails sends its own signed format.run.terminal POST, as covered in Sume Format run lifecycle. Otherwise, poll the queue's status_url.

There is also no public list-queues or cancel-queue endpoint. Cancel one child with POST /v1/format-runs/{run_id}/cancel; that marks its item canceled and frees the slot for the next queued item.

What happens if I send the same batch twice?

Send Idempotency-Key on the create; keys are scoped to one Format. The same key with the same { concurrency, items } returns 202 and the existing queue, not a second one. The same key with a different payload is 409 idempotency_conflict, and details.queue_id names the original. Unlike a single run, a bulk replay stays 202 and has no idempotency_hit field, so mint a fresh key for each new batch. More on key design: idempotency keys for AI video APIs.

What are the limits of a bulk queue?

• Up to 100 items per request, and at most 16 child runs in flight per queue.
• Workspace generation concurrency, the wallet, and each item's spend cap still apply to every child.
• No queue-level webhook, no list-queues endpoint, and no cancel-queue endpoint.
• Create spends the write budget. Polling spends the read budget, which is forty times the write one.
• Service-account keys cannot create bulk queues, and a team Format needs a key issued in that team's workspace.
• An unknown queue id, or another owner's queue, answers 404 format_run_queue_not_found.