Check a GPT Image 2.5 size before you call it: a Python validator

The short answer

Check four things before you send a custom image_size to GPT Image 2.5 on Sume: both edges are multiples of 16, the longest edge is at most 3840, the aspect ratio is at most 3:1, and the total is between 655,360 and 8,294,400 pixels. The Sume Image API docs list those rules. A small function catches a bad size locally, so you do not spend a request on a 400.

The rules

These come straight from the Sume Image API docs for openai/gpt-image-2.5 and openai/gpt-image-2.5-sunburst. The docs also allow named presets and auto; the validator below is only for custom pixels.

• Both edges must be multiples of 16.
• The maximum edge is 3840.
• The aspect ratio must be at most 3:1.
• The image must have 655,360 to 8,294,400 pixels.

The validator

It returns a list of problems, empty when the size is legal. It uses only the standard library.

def check_gpt_size(w: int, h: int) -> list[str]:
    problems = []
    if w % 16 or h % 16:
        problems.append("edges must be multiples of 16")
    if max(w, h) > 3840:
        problems.append("max edge is 3840")
    if max(w, h) / min(w, h) > 3:
        problems.append("ratio above 3:1")
    px = w * h
    if not 655_360 <= px <= 8_294_400:
        problems.append(f"{px:,} px outside 655,360-8,294,400")
    return problems

sizes = [(1024, 1024), (1920, 1080), (1920, 1088), (3840, 2160),
         (1080, 1350), (1024, 1280), (4096, 2048), (800, 800)]
for w, h in sizes:
    print(f"{w}x{h}", check_gpt_size(w, h) or "ok")

What it says about common sizes

Running the eight sizes gives the results below. The pixel counts are width times height.

Fixing a size that fails

When a check fails, repair it in a fixed order. First round each edge to the nearest multiple of 16, for example 1080 up to 1088. Then clamp the longest edge to 3840. Then, if the ratio is above 3:1, shorten the long edge until it passes. Last, scale both edges together if the pixel total is outside the range. Re-run the check after each step, since a fix for one rule can break another.

For delivery sizes that GPT cannot render, such as 1080 x 1350, render the nearest legal box and resize afterwards. That is the approach the docs describe for 4:5, and it costs a few lines of Pillow.

Run the validator where the size is chosen, before the HTTP call, and raise an error with the failed rule in the message. A validation error you raise yourself is faster and clearer than a 400 from the API, and it keeps bad sizes out of retry loops, where they would fail again each time.

Keep the four limits in one constant block at the top of the module. If the docs change a limit, you will have one line to edit, and the table in this post is the place to compare the numbers against the current docs page.

Call check_gpt_size before you build the body. If it returns problems, round each edge to the nearest multiple of 16, or render at a legal size and crop or resize afterwards. For an Instagram 4:5 portrait, the Sume docs say to treat 1080 x 1350 as a post-step target, and the repo's size catalog uses 1024 x 1280 as the legal 4:5 box.

The docs also say Sume rejects a parameter it does not list with 400 unsupported_parameter, so a size that the model cannot take fails fast rather than being silently changed.