Bulk run for an ad matrix: 3 hooks by 4 ratios in 12 queue items

Twelve hook-by-ratio combinations fit comfortably in one bulk run, which accepts 1 to 100 items and a concurrency of 1 to 16. Submit them in a fixed order, derive each file's name from its index, and read each child's receipt for the result.

The shape of the queue

Build the matrix and the name map

Each item sends its hook and ratio as input, which is data the Format reads. The Format you call must be written to use those keys; acme/ad-matrix is a placeholder.

import itertools, os, uuid, requests

API = "https://api.sume.com"
H = {"Authorization": f"Bearer {os.environ['SUME_API_KEY']}"}
hooks = ["save-time", "cut-cost", "less-risk"]
ratios = ["1:1", "4:5", "2:3", "9:16"]
combos = list(itertools.product(hooks, ratios))
items = [{"instruction": f"Ad creative for hook {h}", "input": {"hook": h, "ratio": r}}
         for h, r in combos]
r = requests.post(f"{API}/v1/formats/acme/ad-matrix/bulk-runs",
                  headers={**H, "Idempotency-Key": str(uuid.uuid4())},
                  json={"concurrency": 4, "items": items}, timeout=30)
r.raise_for_status()
q = r.json()["data"]
names = {i: f"{h}_{r.replace(':', 'x')}" for i, (h, r) in enumerate(combos)}
print(q["status_url"], len(names), "items")

After the queue

Poll status_url until status is completed, branch on counts.failed, and read each run_id at GET /v1/format-runs/{run_id}. Retry only the failed indexes in a new queue with a fresh Idempotency-Key.