Image API 200 or 202: branch on the status code, not the body

POST /v1/images waits up to 30 seconds. If the image is ready it returns 200 with data[].url; if not, it returns 202 with a job envelope that carries status_url and result_url. The two bodies have different shapes, so a client must branch on the status code first and read the body second.

When you get a 202

The Image API docs list three triggers: the generation did not finish inside the budget, you sent mode "async", or you sent mode "webhook" with a webhook_url. Slow settings such as 4K, high quality and large n are the likeliest to degrade to 202. The job result is then read from the standard job endpoints described in Jobs and results.

A handler

This function makes the one request and returns either the image URLs or the two job URLs. It uses only fields shown in the docs.

import os
import requests

URL = "https://api.sume.com/v1/images"
HEAD = {"Authorization": "Bearer " + os.environ["SUME_API_KEY"]}


def generate(prompt):
    r = requests.post(URL, headers=HEAD, json={
        "model": "openai/gpt-image-2.5",
        "prompt": prompt,
        "quality": "medium",
    }, timeout=60)
    r.raise_for_status()
    body = r.json()
    if r.status_code == 200:
        return {"urls": [d["url"] for d in body["data"]]}
    data = body["data"]
    return {"status_url": data["status_url"], "result_url": data["result_url"]}


if __name__ == "__main__":
    print(generate("a ceramic mug on a wooden table"))

What the handler leaves out

It does not poll. When you get the job URLs, call status_url until the job ends, then fetch result_url. Pass an Idempotency-Key header on retries so a repeat does not create a second job. Failed or cancelled generations are not billed, so a retry after a failure does not double-charge.