Which Sume image models take references and masks: a Python check

Ask the catalog. GET /v1/images/models returns each model with a supported_parameters object, and the reference ceiling is the max of the input_references range; a model with no such entry takes no references. The script below prints that for every model, plus whether mask_url and aspect_ratio appear. Run it before you pick a model for an edit job, because the list changes and a copy in a blog post ages.

The script

It uses only the standard library, reads the key from SUME_API_KEY, and handles models without references. The capabilities function is separate from the HTTP call, so you can test it on sample JSON.

import json, os, urllib.request

def capabilities(models):
    for m in models:
        params = m.get("supported_parameters", {})
        refs = params.get("input_references")
        yield {
            "id": m["id"],
            "max_refs": refs["max"] if refs else 0,
            "mask_url": "mask_url" in params,
            "aspect_ratio": "aspect_ratio" in params,
        }

def main():
    req = urllib.request.Request(
        "https://api.sume.com/v1/images/models",
        headers={"Authorization": f"Bearer {os.environ['SUME_API_KEY']}"},
    )
    with urllib.request.urlopen(req, timeout=30) as resp:
        models = json.load(resp)["data"]
    for row in capabilities(models):
        print(row)

if __name__ == "__main__":
    main()

How to read the output

The Image API docs define the descriptors: an enum is an allowlist, a range is an integer between min and max, and a boolean is supported when present. If a request sets a parameter that the model does not list, Sume answers 400 unsupported_parameter and does not drop it silently. That is why the check is cheap insurance: a request with mask_url sent to a model without it fails fast with a 400, not with a surprising result.

Two caveats

Reference limits and masks are only half of a model choice. Output shape, price and speed matter too, and the same list call returns aspect_ratio values so you can see whether a model offers the shape your placement needs. Seedream 4.5's example in the docs lists 1:1, 16:9, 9:16, 4:3 and 3:4, with no 4:5, so a feed shape may need a crop after the edit.

Ideogram's own page describes masks with black marking the edit area. The Sume docs do not list mask_url for Ideogram 4.5, so do not send one; the script will tell you whether the live catalog does. Also note that the 400 comes before billing, and a failed generation is not billed.

Pair the output with the endpoint record when cost matters. GET /v1/images/models/{model_id}/endpoints lists pricing entries such as output_image per image, and a token-priced model may list separate entries per token type. The list endpoint tells you what a model can do; the endpoint record tells you what it costs to do it.

Run the script on a schedule if you depend on a capability: store the output as JSON, diff it against the last run, and alert on changes. A model that gains or loses a parameter then shows up as a diff, not as a failed job in production.

A pre-flight check for a specific request is in checking an image request against the catalog, and the mask errors are listed in mask_url returns 400 on other models.