Sume image API 400 "accepts at most N input_references"

If POST /v1/images returns 400 invalid_request with the message <model> accepts at most N input_references., you sent more reference images than that model's catalog allows. On Sume the ceiling is 16 for openai/gpt-image-2.5 and openai/gpt-image-2.5-sunburst and 10 for the other edit-capable rows. Models that are text-to-image only have a ceiling of 0 and answer any reference with 400 unsupported_parameter.

The limit comes from the model's input_references descriptor, which you can read before you call. This post lists the numbers and the two different errors.

What is the limit for each model?

The numbers are built from the Sume image catalog code: 16 for the two GPT Image 2.5 ids, 10 for every other edit-capable row, 0 for rows that are text-to-image only. Reference URLs must also be public HTTPS, and localhost, private-network and non-HTTPS URLs are rejected before submission.

Why can the listed number be higher than the vendor's?

The Sume descriptor is a ceiling on what Sume will pass on, not a promise that the upstream model uses every image. xAI's image generation guide says Grok Imagine edits from up to 5 source images, and Black Forest Labs' FLUX.2 overview says the pro and flex variants take up to 8 references through the API (10 in the playground). Sume lists 10 for both rows.

I could not confirm from those pages what happens between the vendor figure and Sume's 10, so keep Grok to 5 and FLUX.2 to 8 until you have tested your own sets. Seedream 4.5 is a concrete case where the number is not the whole story: its edit path in the Sume code passes only the first 10 URLs and always asks for one output image.

What do the two errors look like?

Too many references is an invalid_request and carries field: input_references and the max in its details, which is enough for a client to trim the list. A reference on a text-only model is unsupported_parameter with a catalog_url pointing back to /v1/images/models. Both come back during validation, before any generation starts, so they cost nothing.

• Over the limit: 400 invalid_request, <model> accepts at most N input_references.
• Text-only model: 400 unsupported_parameter, input_references is not supported. <model> is text-to-image only.
• Bad URL: rejected before submission when it is not public HTTPS.

How do I check before I send?

Fetch the catalog once, read each model's input_references.max, and trim your list to it. If the model has a max of 0, route the job to an edit-capable model instead of sending it anyway.

import os, requests

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

def max_refs(model):
    r = requests.get("https://api.sume.com/v1/images/models", headers=H, timeout=30)
    r.raise_for_status()
    row = next(m for m in r.json()["data"] if m["id"] == model)
    return row["supported_parameters"]["input_references"]["max"]

def trim_refs(model, urls):
    cap = max_refs(model)
    if cap == 0:
        raise ValueError(f"{model} is text-to-image only")
    return [{"type": "image_url", "image_url": {"url": u}} for u in urls[:cap]]

if __name__ == "__main__":
    urls = [f"https://example.com/ref-{i}.jpg" for i in range(12)]
    print(len(trim_refs("openai/gpt-image-2", urls)))

What if I need more than the cap?

Merge references into a contact sheet or collage so that one URL carries several subjects, and say in the prompt which panel is which. That trades some detail for count, so keep it for style and prop references, not for faces. Our GPT Image 2.5 16-reference post covers the highest ceiling, and the FLUX.2 multi-reference post covers the vendor-versus-Sume gap in detail.

How should I order and choose references?

More references are not automatically better. Each one competes for the model's attention, so send the images that carry a decision: the subject, the style target, the prop that must appear. Drop near-duplicates, and avoid sending two photos of the same thing from almost the same angle.

Tell the model what each image is for in the prompt. Where the model expects it, naming the images in order helps, and the GPT Image 2.5 numbered references post shows the pattern for that family. For other rows, say it in plain words and test one set before you scale up.