Sume images API n=5 returns 400 though the docs say up to 10

The Sume Image API docs say you can request up to 10 images per call with n, and the request table says n is 1 to 10. In practice the model's own range wins: n: 5 on any current Sume image model returns 400 invalid_request, because the catalog range is 1 to 4 for most rows and narrower for a few. The 10 is a request-level ceiling, not what any model accepts today.

The docs do add that per-model ceilings are lower and tell you to read the n range descriptor from the catalog. That is the line to follow.

What range does each model have?

The ranges below are the n descriptors in the Sume catalog. Most rows share 1 to 4. Grok Imagine is 1 to 1, and Soul advertises 1 to 4 but only accepts 1 or 4 in a request.

Why would the docs and the catalog disagree?

The docs state the request-level ceiling of 10 and say the per-model ceilings are lower. Sume applies the per-model range from its own catalog, so the field is documented up to 10 while every catalog model limits it to 4 or less.

Grok is the sharpest example. xAI's image generation guide says one request can return up to 10 images, but Sume serves one image per call on that row, so n: 2 fails there. If you port code from xAI's own API, your batch size is the first thing to change.

How do I generate eight images then?

Loop calls with n set to the model's maximum and collect the URLs. Remember that a sync call waits up to 30 seconds and then returns 202 with a job envelope instead of the images, so handle both shapes. Bigger batches, 4K and high quality are the combinations most likely to pass the budget.

Billing is per image, and the docs say cost_usd x n is what you pay, so a loop of two calls with n: 4 costs the same as eight single images on a model with a flat price, and a failed or cancelled call is not billed.

import os, requests

H = {"Authorization": f"Bearer {os.environ['SUME_API_KEY']}"}

def batch(model, prompt, total, per_call=4):
    urls, jobs = [], []
    while len(urls) + len(jobs) * per_call < total:
        r = requests.post("https://api.sume.com/v1/images", headers=H, timeout=60,
                          json={"model": model, "prompt": prompt, "n": per_call})
        r.raise_for_status()
        body = r.json()
        if r.status_code == 200:
            urls += [d["url"] for d in body["data"]]
        else:
            jobs.append(body["data"]["job"]["id"])
    return urls, jobs

if __name__ == "__main__":
    print(batch("google/nano-banana-2", "Paper boat on a pond", 8))

What about the 202 jobs?

A 202 means the generation is still running, not that it failed. Poll GET /v1/jobs/{id}/status and read GET /v1/jobs/{id}/result, or submit with mode: "webhook" and let Sume call you back. The jobs and results guide describes both.

For Grok, set per_call to 1 and expect eight calls. The Grok n-parameter post covers that case on its own, and the Nano Banana post covers the 1 to 4 range there.

What should my client do with a 400 on n?

Read details.min and details.max from the error body and retry once with the clamped value, or split the batch. Do not retry the same body, since a validation failure will repeat. Because rejected requests are not generated, a retry after the fix costs only the call that succeeds.

Set a per-model batch size in config, taken from the catalog at start-up, so a change in a range is picked up without a deploy. The default of 4 is right for most rows today and wrong for Grok.