GPT Image 2.5 image_size rules: validate in Python before you send

Check four rules locally before you send a custom image_size to GPT Image 2.5: both edges are multiples of 16, the longest edge is at most 3840, the aspect ratio is at most 3:1, and total pixels fall between 655,360 and 8,294,400 (Image API docs). Anything outside is a request error, and a 2-second local check saves a round trip.

These rules apply to the custom size field, not to the named aspect ratios. If you only need a standard shape, aspect_ratio is simpler.

What are the rules?

From the Sume docs on GPT Image 2.5, read 2026-10-01.

What does the checker look like?

It returns a list of problems, empty when the size is fine.

def check(w: int, h: int) -> list[str]:
    bad = []
    if w % 16 or h % 16:
        bad.append("edges must be multiples of 16")
    if max(w, h) > 3840:
        bad.append("max edge is 3840")
    if max(w, h) > 3 * min(w, h):
        bad.append("aspect ratio is over 3:1")
    px = w * h
    if px < 655_360 or px > 8_294_400:
        bad.append("pixels must be 655,360 to 8,294,400")
    return bad


for size in [(2048, 1152), (1000, 1000), (3840, 2400)]:
    print(size, check(*size) or "ok")

How do I use it?

Run check on any size your users type in, show the messages, and send only valid sizes. The result of a size that passes also affects price, so read the cost in usage.cost and budget from that, not from the pixel count.

Rounding a requested size to a valid one

If a user asks for 1000 x 700, round each edge to the nearest multiple of 16 (1008 x 704) and run the checker again. Rounding changes the ratio slightly, so if an exact ratio matters, use the named aspect_ratio instead and crop afterwards.

For tall formats such as a 9:16 story, 1152 x 2048 passes all four rules: both edges are multiples of 16, the long edge is under 3840, the ratio is under 3:1 and the area is 2,359,296 pixels.

Limits

The rules can change when the docs change, so treat the numbers here as dated to the read. The check does not know about other models: a Banana row uses resolution tiers and aspect_ratio. An explicit pixel size field is not supported at all.