n=10 on the Sume Image API: docs say 10, catalog says 4 (Grok 1)

The Sume Image API documents n as 1 to 10 images per call, but no model in the catalog allows 10: the ceiling is 4 for most models, 1 for x-ai/grok-image, and exactly 1 or 4 for higgsfield/soul. A request that goes over the model's ceiling returns 400 invalid_request with the allowed range.

The docs say as much in one sentence: "Per-model ceilings are lower. Read the n range descriptor from the catalog." This post turns that sentence into a rule for code.

What the 400 looks like

If n is outside the model's range, Sume answers 400 invalid_request with a message of the form "n must be between 1 and 4 for the model", and details carries the field name with min and max. For Soul, a value of 2 or 3 is inside the 1 to 4 range but is rejected with details.allowed of [1, 4], because that model batches only one or four.

If a model had no n descriptor at all, the field would return 400 unsupported_parameter instead, which is a different failure.

Batching past the ceiling

To get ten images from a model whose ceiling is 4, send three requests: 4, 4 and 2. The price is linear, because Sume bills cost_usd times n: ten images on Qwen Image at 0.025 USD are 0.25 USD whether you send them as 4 + 4 + 2 or as ten calls of 1.

The chunking code is small and avoids the 400 completely if the ceiling comes from the catalog and not from a constant in your code.

def chunks(total, ceiling):
    full, rest = divmod(total, ceiling)
    return [ceiling] * full + ([rest] if rest else [])


print(chunks(10, 4))  # [4, 4, 2]
print(chunks(10, 1))  # ten calls of one image
print(chunks(8, 4))   # [4, 4]

Why the two numbers differ

The n field in the request schema is shared by every image model, so the schema allows the widest range, 1 to 10. Each model then publishes its own descriptor, and the request check compares your value against that descriptor, not against the schema. The docs page describes the schema, and the catalog describes the models.

Practically: never hard-code 10, never hard-code 4. A client that stores the ceiling next to the model id keeps working when Sume adds a model that really does allow more, and fails loudly in your own tests, rather than at 3 a.m., when a model's ceiling is lower than you assumed.

Billing for a batch

Sume bills image generation all-or-nothing. A completed generation is charged in full from the endpoint pricing, and the charge is cost_usd times n. A failed or cancelled generation is not charged. For a three-slice batch of 4, 4 and 2 on a 0.025 USD model, the total is 10 x 0.025 = 0.25 USD, and if the last slice fails you pay for 8 images, 0.20 USD.

Read the ceiling at run time

GET /v1/images/models returns each model's supported_parameters, including n as a range descriptor with min and max. Read it once at start-up and cache it for the process. Each of the slices you send is a normal request, so each can return 200 or 202, as described in the Image API docs.

A Soul-specific rule is worth hard-coding next to the catalog read: if the model is higgsfield/soul, round the slice to 1 or 4, since the range descriptor alone does not tell you that 2 and 3 are refused.