Sume bulk Format runs: 100 items, one concurrency window, cost control

Send one POST /v1/formats/{handle}/{slug}/bulk-runs with up to 100 items and a concurrency number. The queue is server-side, so you do not drive the fan-out from your laptop, and every item is an ordinary Format run with its own receipt. Poll GET /v1/format-run-queues/{queue_id} for the queue and GET /v1/format-runs/{run_id} for each child.

What the API gives you

Scopes match single runs: formats:write to create and formats:read to poll. Service-account keys cannot create Format runs or bulk queues and fail with 403 insufficient_scope. There is no public list-queues or cancel-queue endpoint, so cancel a child at POST /v1/format-runs/{run_id}/cancel.

Filter before you queue

A decision model can pick which items go into the queue, so that you pay only for the ones that pass. Build the items list after the gate, and send an Idempotency-Key for the queue request.

def build_items(rows, keep):
    items = [
        {"instruction": r["ask"], "input": {"url": r["url"]}}
        for r in rows
        if keep(r)
    ]
    if not 1 <= len(items) <= 100:
        raise ValueError(f"need 1-100 items, got {len(items)}")
    return {"concurrency": 3, "items": items}


rows = [{"ask": f"clip {i}", "url": f"https://example.com/{i}.jpg"} for i in range(5)]
print(build_items(rows, lambda r: r["ask"] != "clip 2"))

Check the docs before you ship

Sume's limits and field names change faster than blog posts do. Read the linked docs pages for the current request fields before you ship, and send a dry_run or a low spend cap on your first real call.