size vs image_size vs aspect_ratio: which field wins on Sume images

POST /v1/images has four fields that all sound like they set the output shape: size, image_size, aspect_ratio and resolution. They do different jobs, and sending two of them is where surprises come from.

Sume's rules, from the contract and the public Image API docs (read 2026-10-07): image_size has priority over aspect_ratio. size is tier shorthand only and rejects WxH. resolution is a normalized tier (512, 1K, 2K, 4K; 0.5K is an alias for 512; Soul uses 720p and 1080p). aspect_ratio is a per-model native list, not a shared subset.

The four fields

What to send, by model family

For GPT Image 2.5, Seedream, Flux, Qwen and Recraft, send image_size when you need exact pixels and aspect_ratio when a ratio is enough. On GPT, custom pixels need both edges to be a multiple of 16, a maximum edge of 3840, an aspect of at most 3:1, and 655,360 to 8,294,400 pixels.

For the Nano Banana models, there is no free pixel size. Ask for 1080x1350 and Sume sends aspect_ratio: "4:5" plus a job target_pixels note, because the exact 1080x1350 is a documented post-step, not a native size. For Imagen, Grok, Ideogram and Soul, aspect_ratio is the only sizing field; pixel size is snapped to the nearest native ratio.

The catalog is the allowlist. If a model does not list a parameter in supported_parameters, the request fails with 400 unsupported_parameter instead of dropping it. That means sending resolution to a model with no resolution tiers is an error, not a no-op.

Reading the catalog before you send

This prints which sizing fields a model advertises.

import os, requests
H = {"Authorization": "Bearer " + os.environ["SUME_API_KEY"]}
r = requests.get("https://api.sume.com/v1/images/models", headers=H, timeout=30)
for m in r.json()["data"]:
    sp = m["supported_parameters"]
    print(m["id"], [k for k in ("aspect_ratio", "resolution", "image_size") if k in sp])

Source: Sume Image API docs (read 2026-10-07).