GPT Image API: Validate and Deliver Transparent PNGs

Ship a Real Transparent PNG from the GPT Image API

A product cutout looks correct on a white preview card. The designer places it on a dark campaign banner and a pale rectangle appears around it. Somewhere between generation and delivery, “transparent background” became a visual description instead of a property of the file. The image request succeeded, the filename ended in PNG, and the asset was still unusable. This recipe follows the bytes far enough to catch that failure before a creative team discovers it.

The deliverable is a static product illustration with genuine transparent pixels, preserved edge detail, and a verified download. We will request PNG output from the GPT Image API, decode the response, inspect the alpha channel, make light and dark review proofs, and check the delivered artifact. The code is a reference recipe; no image is generated as part of this article. Model access, accepted parameters, and gateway support must be checked for the route you actually use.

Write an asset specification before the prompt

Our example asset is an unbranded ceramic mug for a reusable layout component. It must show the complete handle and base, leave space around the silhouette, and contain no text, floor plane, or cast shadow. The surrounding canvas must be transparent. This brief makes the result easier to inspect because an opaque shadow is not secretly part of the intended design. If your asset needs a soft shadow, define that as an additional creative requirement and review its partial transparency separately.

Separate the master asset from its previews. The transparent master is suitable for composition; a white-background proof is suitable for reviewing light edges; a dark-background proof reveals pale fringes. Name those files differently so a content editor cannot mistake a proof for the deliverable. The existing presentation graphics workflow offers an adjacent use case where this distinction matters: a flattened preview may look acceptable on one slide theme and fail immediately on another.

OpenAI's image generation guide documents transparent backgrounds for supported GPT Image models and compatible output formats. This recipe requests background="transparent" and output_format="png" explicitly. Do not rely only on a prompt saying “cut out,” and do not leave format selection to a later media optimizer. Parameter support is model-specific; choose the model identifier from current account access rather than copying an old model name into a permanent production configuration.

Current image interfaces include more than one delivery shape. The Image API generation reference specifies the request and returned image data for the dedicated endpoint. This article uses that endpoint and base64 image data, not a Responses image-generation tool call. The distinction makes parsing deliberate. The existing Images API overview can orient readers to image workflows, while this recipe concentrates on the static asset acceptance boundary.

Request one asset and retain the original bytes

The native reference below requires the OpenAI Python SDK. Set OPENAI_API_KEY, OPENAI_IMAGE_MODEL, and optionally IMAGE_OUTPUT_DIR, choosing a new directory for each attempt. The model must support the requested transparent PNG combination. A finite request timeout keeps the client behavior explicit, and automatic retries are disabled so an ambiguous connection failure does not quietly create another paid generation. If a timeout occurs, record it as an unresolved attempt and investigate before repeating the request.

# Native OpenAI reference; requires the openai package.
import base64
import hashlib
import json
import os
from pathlib import Path
from openai import OpenAI

folder = Path(os.environ.get("IMAGE_OUTPUT_DIR", "image-candidate"))
folder.mkdir(parents=True, exist_ok=False)
client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url="https://api.openai.com/v1",
    timeout=180.0,
    max_retries=0,
)
model = os.environ["OPENAI_IMAGE_MODEL"]
response = client.images.generate(
    model=model,
    prompt="A single unbranded teal ceramic mug, studio product illustration. "
           "Show the entire mug and handle with clear empty margin on all "
           "sides. Isolate the object on a transparent background. No text, "
           "no floor, no cast shadow, no checkerboard pattern.",
    n=1,
    size="1024x1024",
    background="transparent",
    output_format="png",
)
if not response.data or len(response.data) != 1:
    raise RuntimeError("Expected one image result")
encoded = response.data[0].b64_json
if not isinstance(encoded, str) or not encoded:
    raise RuntimeError("Missing base64 image data")
# Local intake limit for this recipe, not a provider maximum.
if len(encoded) > 40_000_000:
    raise RuntimeError("Encoded image exceeds the local intake limit")
raw = base64.b64decode(encoded, validate=True)
if not raw.startswith(b"\x89PNG\r\n\x1a\n"):
    raise RuntimeError("Returned bytes are not a PNG candidate")
path = folder / "mug-original.png"
path.write_bytes(raw)
manifest = {
    "model_requested": model,
    "background_requested": "transparent",
    "format_requested": "png",
    "file": path.name,
    "sha256": hashlib.sha256(raw).hexdigest(),
    "byte_length": len(raw),
    "review_status": "pending_alpha_and_visual_checks",
}
(folder / "generation-manifest.json").write_text(
    json.dumps(manifest, indent=2), encoding="utf-8"
)
print(path)

The Python base64 reference documents strict validation during decoding. That check establishes that the payload is decodable, not that it depicts the requested object. Likewise, the PNG signature only identifies a candidate format; it does not prove the whole file is valid or transparent. Keep the original bytes and their checksum before any transformation. This gives you a stable reference when a later export, resize, or content delivery layer changes the asset.

Do not treat base64 text as a durable media URL. Decode it once, store the image under your application's access policy, and record the artifact identifier in the job. The larger image platform implementation guide provides surrounding product context. Here the important boundary is narrower: a successful response creates a candidate file, and neither the API return nor a file write authorizes publication.

PNG is a container; transparency is a pixel property

The W3C PNG specification defines alpha and transparency representations. An image can be a perfectly valid PNG while every pixel is opaque. A checkerboard painted into the image is also opaque artwork, even though it resembles an editor's transparency display. Your validator must inspect decoded pixel transparency rather than judge the filename or the appearance of a thumbnail. This is why a white product on a white preview cannot establish whether its background is actually empty.

PNG transparency can be represented in different ways, including palette transparency. Converting a decoded image to RGBA is a convenient way to inspect its effective alpha values. It is not a repair operation: converting an opaque RGB image adds a fully opaque alpha channel. The Pillow Image reference documents the conversion, channel inspection, integrity checks, and compositing methods used below. We preserve the original file and use the converted copy only for measurement and proof generation.

For this solid mug recipe, require both fully transparent and fully opaque pixels. That rejects an opaque rectangle and an entirely invisible image. It does not establish that the background is correctly removed everywhere. A single transparent corner could satisfy the rule while most of the background remains. The report therefore includes transparent-pixel counts and the visible bounds, and visual review remains necessary. Do not impose the same opacity rule on a different brief such as a translucent glass illustration.

# Standalone local inspection; requires Pillow. No API calls.
# Usage: python inspect_alpha.py image-candidate/mug-original.png
import hashlib
import json
import sys
import warnings
from pathlib import Path
from PIL import Image

source = Path(sys.argv[1])
raw = source.read_bytes()
if len(raw) > 30_000_000:
    raise SystemExit("Local decoded-file limit exceeded")
Image.MAX_IMAGE_PIXELS = 20_000_000  # Local intake policy.
warnings.simplefilter("error", Image.DecompressionBombWarning)
with Image.open(source) as probe:
    if probe.format != "PNG":
        raise SystemExit("Expected PNG format")
    if getattr(probe, "n_frames", 1) != 1:
        raise SystemExit("This delivery recipe accepts static images only")
    probe.verify()
# Reopen after verify() before decoding image data.
with Image.open(source) as loaded:
    loaded.load()
    rgba = loaded.convert("RGBA")
alpha = rgba.getchannel("A")
histogram = alpha.histogram()
total = rgba.width * rgba.height
transparent = histogram[0]
opaque = histogram[255]
partial = total - transparent - opaque
bounds = alpha.getbbox()
passed = transparent > 0 and opaque > 0 and bounds is not None
report = {
    "file": source.name,
    "sha256": hashlib.sha256(raw).hexdigest(),
    "width": rgba.width, "height": rgba.height,
    "alpha_min_max": alpha.getextrema(),
    "transparent_pixels": transparent,
    "partially_transparent_pixels": partial,
    "opaque_pixels": opaque,
    "visible_bounds": bounds,
    "structural_alpha_check": "pass" if passed else "fail",
    "visual_review": "required",
}
source.with_name("alpha-report.json").write_text(
    json.dumps(report, indent=2), encoding="utf-8"
)
for name, color in (("light", (245, 245, 245, 255)),
                    ("dark", (25, 30, 40, 255))):
    background = Image.new("RGBA", rgba.size, color)
    proof = Image.alpha_composite(background, rgba).convert("RGB")
    proof.save(source.with_name(f"proof-{name}-flattened.png"))
print(json.dumps(report, indent=2))
if not passed:
    raise SystemExit("Candidate failed the mug recipe's alpha check")

The numeric limits in this script are local intake choices, not model specifications. A larger production asset may need a different pixel budget. The integrity check detects structural problems, and reopening the file allows normal decoding afterward. Raising decompression warnings to errors prevents unexpectedly large decoded images from passing silently into this particular workflow. Those controls protect the inspection process; they do not make an artistic judgment about whether the mug looks right.

Visible bounds tell you whether nontransparent pixels reach the edges, but they should not automatically trigger a tight crop. A handle may sit near the border while the mug body is centered; cropping to the silhouette can remove the spacing that the layout component expects. Preserve the agreed canvas dimensions for interchangeable assets. If you do create a cropped variant, record it as a derivative and repeat alpha and visual checks against that file.

Review the edge, then the object

Inspect both proofs at normal display size and at a larger scale. On the dark proof, look for a white fringe around the handle or a rectangular haze outside the subject. On the light proof, look for dark halos and missing pale details. Examine the empty space inside the handle as well as the outer boundary. A silhouette can have a correct exterior while retaining an opaque patch in an interior opening.

Do not reject every partially transparent pixel. Smooth edges commonly need intermediate alpha values to avoid a jagged outline when composited. The question is whether those pixels describe the intended edge or carry an unwanted background color. Aggressively forcing alpha to either zero or maximum can make the histogram simpler while visibly damaging the asset. For this recipe, the histogram is a diagnostic, and the light and dark proofs expose defects that the histogram cannot describe.

Review the object independently of transparency. Check that the handle joins the body plausibly, that the base is complete, and that the prompt did not introduce lettering or additional objects. The earlier GPT Image prompting and migration article is useful adjacent reading, but a benchmark or an attractive preview cannot replace asset-specific review. Keep feedback concrete: “opaque patch inside handle” gives the next generation a more useful target than “make it cleaner.”

If the candidate fails, retain its manifest and rejection reason before generating another. Compare revisions using the same proof backgrounds and intended display size. This makes a newly introduced halo visible even when the overall illustration improves. Avoid repeatedly transforming a failed original until nobody can explain how it was changed. A clear chain from original to reviewed derivative is more useful to a production team than a directory of files named final, final-new, and final-again.

Test the file that consumers receive

Upload the reviewed transparent master with a PNG content type and a versioned asset name. Then download it through the exact URL used by the application. Compare its bytes or checksum with the accepted artifact when the delivery path is meant to be lossless. If your media system intentionally resizes or transcodes, treat the delivered version as a new derivative and run the same alpha inspection on that output. A successful upload does not establish the properties of a transformed download.

The multimodal production architecture guide places this handoff in a wider application context. Common failure points include a thumbnail generator that converts to RGB, a format optimizer that chooses JPEG, and a content editor who uploads the light proof instead of the master. The practical acceptance question is precise: does the file delivered to the target component still contain the transparency and canvas geometry that the component expects?

Use an integration fixture with a known transparent region when testing your delivery pipeline. A small local asset can test upload, transformation, and download behavior without paying for another generation. Keep that delivery fixture separate from the generated mug, because it answers a different question. If the fixture loses alpha after upload, fix the media path before adjusting prompts. If the fixture survives but the mug fails, inspect the candidate and its creative requirements.

Record the chosen image model, requested format, candidate checksum, alpha report, reviewer decision, and published derivative identifier together. This is enough to trace a bad campaign asset without storing the entire base64 response in normal logs. The API observability article offers useful operational patterns for connecting a generation job to its artifacts. Keep public asset URLs separate from any private prompt or review notes that do not belong in a downloadable manifest.

A first 4SAPI test should end with a verified PNG

Inspect the selected image route in the 4SAPI documentation before adapting the native request. Confirm the available model identifier, image-generation endpoint, transparent-background parameter, output format, and response representation. The public OpenAI-compatible base https://4sapi.com/v1 does not by itself prove that every native image option is available. Configure a separate client with gateway credentials only for the confirmed gateway route, and keep the local alpha inspection unchanged.

You can create a 4SAPI account and use one unbranded cutout as a scoped first image request. Save the candidate, inspect its effective alpha, review both proofs, and retrieve the final delivery URL. The accepted result is the image your application can actually composite on a different background. Once that path is established, creative iteration can focus on composition and style without rediscovering whether “transparent PNG” survived the trip.

Primary references

• OpenAI image generation guide
• OpenAI Image API generation reference
• W3C PNG specification
• Pillow Image reference
• Python base64 reference