Python: cheapest Sume image model that lists your aspect ratio

This script finds the cheapest Sume image model that lists a given aspect ratio. It calls GET /v1/images/models, keeps the models whose aspect_ratio descriptor contains your value, reads each model's /endpoints record, and prints the lowest pricing[].cost_usd. For 1:1 it should land on a Higgsfield Soul or GPT Image 2.5 low price; for 20:9 only Grok Imagine lists the ratio, so the answer is Grok.

Everything here comes from the catalog and endpoint schemas in Sume's image docs: supported_parameters holds the descriptors, and pricing: [{billable, unit, cost_usd}] holds the billed amount.

The script

It uses the requests library, one catalog call and one endpoints call per candidate. Set SUME_API_KEY first. Pass the ratio as the first argument.

import os, sys, requests
BASE = "https://api.sume.com/v1/images/models"
H = {"Authorization": "Bearer " + os.environ["SUME_API_KEY"]}
ratio = sys.argv[1] if len(sys.argv) > 1 else "4:5"
models = requests.get(BASE, headers=H, timeout=60).json()["data"]
rows = []
for m in models:
    ar = m.get("supported_parameters", {}).get("aspect_ratio", {})
    if ratio not in ar.get("values", []):
        continue
    ep = requests.get(f"{BASE}/{m['id']}/endpoints", headers=H, timeout=60)
    prices = [float(p["cost_usd"]) for e in ep.json()["endpoints"]
              for p in e["pricing"]]
    if prices:
        rows.append((min(prices), m["id"]))
for cost, mid in sorted(rows)[:5]:
    print(f"{cost:.4f}  {mid}")

What it returns, and what it hides

The script prints the five cheapest. Two caveats come from how the catalog is built. First, a model with several billable lines, such as ChatGPT Image 2.5's tiers, shows its lowest line, so the cheapest result for it is the low tier. Second, the cheapest model is not the best match. Soul and Imagen 4 Fast are text-to-image only, so if your job is an edit, filter on input_references too.

A third caveat is freshness. The catalog is live, so the output of the script changes when Sume adds a model, changes a ratio list or revises a price. That is the point of reading it at run time rather than hard-coding a table, but it means a pipeline that depends on the cheapest answer should log the model id it chose with each batch. When the choice changes, you will know why the bill changed.

To add that filter, test the descriptor m['supported_parameters'].get('input_references', {}).get('max', 0) > 0 before the price call.

Ratios by model, for reference

The catalog lists different ratio sets per model. The table shows how many each lists and whether the wide or tall extremes are present, so you know what the script will find for an unusual ratio.

Extending it

Two additions are common. Add a --edit flag that also requires input_references.max > 0, and add a column for the tier that produced the minimum price so the output says low or medium and not only a number. If you serve several ratios, loop over them and write a table once a day to a file; a diff of that file is a cheap change alarm for the catalog.

Make it a startup check

A script like this is worth running in CI. If a pinned model drops a ratio, or its cheapest price rises, the check fails before a batch does. Cache the catalog for a few minutes; it is a small response, but you do not need it for every request.

Add a timeout and a clear error for a missing key. The script above will raise a KeyError if SUME_API_KEY is not set, which is the right failure for a build step: it stops early and names the variable. Do not default the key to an empty string, because that turns a configuration error into a confusing 401 from the API.

Because prices are the billed amount, no multiplier is needed. If you want the provider list figure, divide by 1.25.

Keep in mind that every figure here is a billed price from Sume's catalog on the date in the table caption. Prices and limits can change, so before a large run, read the endpoint record for the exact model id and compare it with your plan. A one-minute check costs nothing, and it is the only way to be sure the number in your budget is the number on the invoice.