Check a transparent GPT Image 2.5 PNG for real alpha in Python

To get a transparent image from GPT Image 2.5 on Sume, send background: "transparent" with output_format: "png" (or webp), then open the file and confirm it has an alpha channel with some fully transparent pixels. A viewer on a white page will show a white box as "transparent", so the check has to read the pixels, not the picture.

The request fields come from Sume's Image API page, which lists background: auto|transparent|opaque for both openai/gpt-image-2.5 (Flare) and openai/gpt-image-2.5-sunburst. The checking advice comes from OpenAI's Image prompting guide and fal's GPT Image 2.5 guide, read on 2026-10-02.

What do the vendors say about transparent output?

fal's guide says transparent backgrounds need PNG or WebP. OpenAI's guide says to request background="transparent" explicitly and to check the decoded image's alpha channel, including hair, glass and shadows. Those are the three places where cut-outs fail: fine strands, see-through material and soft shadows that were baked into the colour.

Sume's docs also say jpeg is a valid output_format in general, but JPEG has no alpha channel, so pairing it with a transparent request cannot give you a cut-out. Keep png or webp for this job.

How do I request it?

A plain request with the two fields. The image URL comes back in data[0].url, and usage.cost is the USD amount billed.

curl -X POST "https://api.sume.com/v1/images" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2.5",
    "prompt": "A glass perfume bottle with a soft shadow, centred, no background",
    "background": "transparent",
    "output_format": "png"
  }'

What does the check script look like?

This script downloads the result, fails if the image has no alpha channel, and prints how much of it is fully transparent, partly transparent and fully opaque. Run pip install pillow requests first. A real cut-out has a large fully transparent share and a thin band of partial values on the edges; a result that is 100% opaque has no cut-out at all.

import io, sys, requests
from PIL import Image

url = sys.argv[1]
img = Image.open(io.BytesIO(requests.get(url, timeout=60).content))
print("format:", img.format, "mode:", img.mode, "size:", img.size)
if img.mode not in ("RGBA", "LA", "PA") and "transparency" not in img.info:
    sys.exit("no alpha channel: this is not a transparent image")

alpha = img.convert("RGBA").getchannel("A")
hist = alpha.histogram()
total = sum(hist)
clear, solid = hist[0], hist[255]
print(f"transparent {clear/total:.1%}, "
      f"partial {(total-clear-solid)/total:.1%}, "
      f"opaque {solid/total:.1%}")
if clear == 0:
    sys.exit("alpha exists but nothing is transparent")

How should I read the numbers?

The table lists what each outcome means and what to do. The thresholds are rules of thumb, not Sume or OpenAI limits.

What does this not tell me?

It tells you the file has alpha, not that the edges are good. Composite the PNG onto a black and a white square and look at hair and glass. Sume does not offer a halo-detection tool; if the edge is poor, regenerate with a simpler subject or compare approaches in remove background and upscale: which order.

Can I run this on a whole batch?

Yes. Loop over the result URLs from a batch and fail the run if any image has no alpha channel or a transparent share of zero. Catching a bad one early keeps opaque images off the page.

Keep the test backgrounds simple: a near-black and a near-white square show a white halo or a dark fringe at once. For the Sume side of transparency, including the older Image 1.0 transparency option, see the transparency migration post.