Sume Image API n: 1 to 10 per call, lower per-model ceilings

On Sume's Image API, n takes an integer from 1 to 10 for the number of images per request. The docs add that per-model ceilings are lower, so the number you can actually send comes from the n range descriptor in the model's catalog entry. Read GET /v1/images/models first, then budget at the per-image price times n.

What the docs say

Three separate statements on the Image API page combine into the working rule.

Read the ceiling, do not guess

A model that does not list a parameter rejects it with 400 unsupported_parameter, and a value outside the advertised range is a request you can avoid by checking first. The check is one GET.

import os, requests
r = requests.get(
    "https://api.sume.com/v1/images/models",
    headers={"Authorization": f"Bearer {os.environ['SUME_API_KEY']}"},
    timeout=30,
)
r.raise_for_status()
for m in r.json().get("data", []):
    print(m.get("id"))
# Then GET /v1/images/models/{id}/endpoints and read the n range descriptor
# before choosing how many images to ask for in one call.

Budget math

Endpoint pricing lines are the amount charged to the wallet with Sume's margin applied, so a four-image call is four times the one-image price. The response carries usage.cost, the USD amount billed for the call, and token counts are always 0 in v1. Add the cost fields from each response to track a batch; do not multiply a token estimate. The pricing note for ChatGPT Image 2.5 differs, since it is token-metered and the cost varies with quality and size, so measure instead of assuming a flat figure.

A small batching rule

When in doubt, start with n: 1 on a new model, read usage.cost, then raise n once you know one image's price and how long it takes. Keep the status-code check in every client.

n against several calls

One call with n: 4 returns four images in one response and one wait, but all four share the 30 second block. A large n at high quality is one of the combinations the docs name as likely to come back as a 202 job envelope. Four parallel calls of n: 1 finish independently and fail independently, which makes retries cleaner. Use n when you want a quick spread of variants at modest quality, and separate calls when each image is an expensive configuration. Check the status code, not the body shape: 200 is the image response and 202 is the job envelope, read from /v1/jobs/{id}/result.

The docs also say a model whose input_references range is zero rejects references, which is the same descriptor pattern: the catalog entry, not this page, is the final word for each parameter. For image edits, the reference count and n both come from that entry. A script that reads the descriptor once at startup and clamps n to its maximum avoids most 400 responses from batch jobs. Log the clamped value so a later reader can see why a batch returned fewer images than requested.