GPT Image 2.5: image_size wins over aspect_ratio, plus the pixel rules

On Sume's image API, image_size has priority over aspect_ratio, so a GPT Image 2.5 request that sends aspect_ratio: "1:1" and image_size: {"width":1280,"height":720} returns a 16:9 frame, not a square. The ratio does not break the request; it is simply ignored. The Image API docs list the custom-pixel rules: both edges multiples of 16, longest edge at most 3840, aspect ratio at most 3:1, and 655,360 to 8,294,400 pixels in total.

That makes conflicts easy to write by accident. A config that stores a default ratio and a per-job size will quietly use the size.

What are the exact rules?

The rules are arithmetic, so test them before you pay for a call. Note that size is a different field: it takes a resolution tier only and rejects pixel values.

How do I check a size in code?

This validator mirrors the documented limits. It is a preflight, not a replacement for the API's own 400, which stays the source of truth.

def gpt_size_ok(w: int, h: int) -> bool:
    if w % 16 or h % 16:
        return False
    if max(w, h) > 3840:
        return False
    if max(w, h) / min(w, h) > 3:
        return False
    return 655_360 <= w * h <= 8_294_400

for size in [(1280, 720), (1920, 1080), (1920, 1088), (3840, 1280), (3840, 1024)]:
    print(size, gpt_size_ok(*size))

What should I do about conflicts?

Pick one source of truth. If you need pixels, send only image_size. If you need a ratio and the model's native size, send only aspect_ratio. The price follows the pixels you ask for: on GPT Image 2.5 at high quality 1280x720 bills about $0.0356, against $0.0659 for 1024x1024. Prices here are list x 1.25 in dollars per image before whole-cent rounding; the catalog's billable formula reads "list x 1.25, ceil usd cents", so confirm the first charge in usage.cost and budget from the invoice, not from the sum.