Q4 creative test matrix: 3 hooks by 3 Formats in one 9-item bulk run

A bulk queue is built per Format, so a matrix that spans styles is three queues, not one. For one SKU, take three hooks and three catalog Formats and queue three items on each, nine runs in all. Give every item the same cap and the worst-case spend is a number you can read before you press go: nine items at $15 is $135.

What does the matrix look like?

How do I queue one row?

Each row is one POST /v1/formats/sume/{slug}/bulk-runs call with three items. Use a fresh Idempotency-Key for each of the three calls: a spent key returns 202 with the old queue and not a new one. Put the same product attachment in every item so that only the style and the hook change.

curl -X POST https://api.sume.com/v1/formats/sume/sume-product-usage-demo/bulk-runs \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: matrix-demo-row-001" \
  -d '{
    "concurrency": 3,
    "items": [
      { "instruction": "Hook A: it sells out by December", "generation_spend_cap_usd": 15,
        "attachments": [{ "type": "input_image", "image_url": "https://cdn.example.com/sku-1.jpg" }] },
      { "instruction": "Hook B: the gift that fits everyone", "generation_spend_cap_usd": 15,
        "attachments": [{ "type": "input_image", "image_url": "https://cdn.example.com/sku-1.jpg" }] },
      { "instruction": "Hook C: three colours, one price", "generation_spend_cap_usd": 15,
        "attachments": [{ "type": "input_image", "image_url": "https://cdn.example.com/sku-1.jpg" }] }
    ]
  }'

What do I attach?

Add an attachments entry of type input_image with the product still to every item, or each run will have no product to show. The call page allows up to 30 images per item.

How do I read the outcome?

Poll each queue at GET /v1/format-run-queues/{id}. Treat completed as finished, not as successful, and read counts.failed. Then compare the nine clips at thumbnail size and pick finalists to run in the ad platform. Sume does not run the test or say which cell performs better.

Why three queues and not one?

The bulk path is /v1/formats/{handle}/{slug}/bulk-runs, so every queue belongs to one Format. That is a limit, but it also keeps a row's results together: one queue id per style, three items inside it, and one counts object per row. When a whole row fails, for instance because the brief did not suit that Format, you see it at once and fix one row.

What are the limits?

• Each cell is a single generated clip, so a gap between two cells may be noise in generation and not in the hook. Rerun a promising cell before you read much into it.
• sume-close-camera-ugc and the usage demo show a person, so check the platform's rules for synthetic people before you run them.
• A queue runs 1 to 16 items at a time, and workspace generation concurrency still applies on top.
• Cancel is per child run, with POST /v1/format-runs/{run_id}/cancel.