Pick an image model by capability from the Sume catalog in Python

New image models arrive faster than hard-coded model ids can follow. Sume's image catalog publishes typed capability descriptors, so your code can ask which model fits a job instead of carrying a table in a config file.

The descriptor types are enum (a list of allowed values), range (min and max integers) and boolean (present means supported). A model that does not list a parameter rejects it with 400 unsupported_parameter, so a filter on descriptors is the same logic the API applies.

A filter that returns matching ids

The function below returns every model that takes at least N references, lists a given aspect ratio, and, if you pass one, lists a resolution tier. It uses only fields documented on the Image API page.

import os, requests
headers = {"Authorization": "Bearer " + os.environ["SUME_API_KEY"]}

def pick(min_refs=0, ratio=None, tier=None):
    r = requests.get("https://api.sume.com/v1/images/models", headers=headers, timeout=30)
    r.raise_for_status()
    out = []
    for m in r.json()["data"]:
        p = m["supported_parameters"]
        if p.get("input_references", {}).get("max", 0) < min_refs:
            continue
        if ratio and ratio not in p.get("aspect_ratio", {}).get("values", []):
            continue
        if tier and tier not in p.get("resolution", {}).get("values", []):
            continue
        out.append(m["id"])
    return out

print(pick(min_refs=5, ratio="4:5", tier="2K"))

What to key on

Match on the descriptor, then price the survivors. Prices live on the per-model endpoints call, GET /v1/images/models/{id}/endpoints, in a pricing array with billable, unit and cost_usd.

Caveats

Some models take custom pixels on image_size instead of a resolution tier, so a missing resolution descriptor does not mean low resolution. The sample treats a missing descriptor as unsupported, which is the conservative choice. Cache the catalog for minutes, not days: the list is the one place new models show up.

How this was checked

Vendor facts come from the pages listed in the sources, read on 2026-10-05. Sume facts come from the Image API docs and the catalog code on main on the same date. Catalogs and limits change, so read the descriptors from GET /v1/images/models before you pin a number in production code.