Image API n or a bulk Format run: which to use for ad variants

Use n on POST /v1/images when every variant shares one prompt and one ratio, and a bulk Format run when each variant needs its own instruction, input, spend cap or webhook. The Image API allows n from 1 to 10 with lower per-model ceilings; a bulk queue allows up to 100 items.

Side by side

Rule of thumb in code

A tiny chooser makes the rule explicit.

def pick(variants: list[dict]) -> str:
    prompts = {v["prompt"] for v in variants}
    ratios = {v["ratio"] for v in variants}
    if len(prompts) == 1 and len(ratios) == 1 and len(variants) <= 4:
        return "Image API with n"
    return "bulk Format run"

print(pick([{"prompt": "a", "ratio": "1:1"}] * 3))
print(pick([{"prompt": "a", "ratio": "1:1"}, {"prompt": "b", "ratio": "2:3"}]))

Cost and failure

Image n bills through one usage.cost on the response. A bulk queue gives you per-item receipts, so one failure does not hide the rest.