Image API n: 10 per call in the schema, lower for each model
The Sume Image API schema allows n from 1 to 10, but each model lists its own n range. How to read the ceiling and what you pay for n images.
The Sume Image API accepts n from 1 to 10 in its schema, but the real ceiling is the n range descriptor in each model row of GET /v1/images/models. Read it before you batch, because a request above the model range is not a silent clamp: a field a model does not list is rejected with 400 unsupported_parameter.
What the docs say
The Image API docs say to use n for up to 10 images per call and that per-model ceilings are lower. Their sample row for Seedream 4.5 shows an n range of 1 to 4 and input_references of 0 to 10, which shows the format, not a promise for that model today. The row you fetch is the one that counts.
Cost and timing with n
Endpoint pricing already includes the Sume margin, so you pay cost_usd times n. Failed or cancelled generations are not charged. Large n is also one of the settings that the docs name as likely to push a request past the 30 second wait and into a 202 job envelope.
| Item | Effect of a larger n |
|---|---|
| Price | cost_usd x n, billed on completion |
| Wait | More likely to exceed 30 seconds and return 202 |
| Range | Per-model, from the n descriptor in the catalog |
| Failure | No charge for a failed generation |
A safe pattern
Read the range, then clamp in your code.
- GET /v1/images/models and find the model row.
- Read supported_parameters.n.max.
- Send min(wanted, max) per call and loop for the rest.
- Use mode async for big batches, so the 30 second wait does not matter.
Sources
Related posts
More in Developers
- Image burst after a model launch: 429 queue_full vs 503 retry plan
Launch week means batches. On Sume, 429 rate_limited, 429 queue_full and 503 provider_capacity_exceeded each need a different retry, plus idempotency keys.
- Sume /v1/images returns 200 or 202: branch on the status code
A slow 4K or xhigh image request on Sume returns 202 with a job envelope, not the image body. A Python client that handles 200, 202 and 502 correctly.
- image_size, aspect_ratio or size: which field wins on Sume
Sume's image API has three size fields. image_size beats aspect_ratio, size takes only a tier, and 4:5 is 1080x1350 portrait. Examples for GPT and Nano Banana.
- Image-to-video not starting on my photo: frame_images vs references
Your photo is a reference, not a first frame, when it goes in input_references. Use frame_images with first_frame on Sume /v1/videos to pin the opening shot.
Written by Sume