The error message is straightforward, and the solution involves a single model swap. The background: "transparent" parameter represents a preview capability available only on specific image model deployments, not all of them. Notably, the model used in OpenAI's official cookbook is not the one supporting this feature.
Error: 400, "Transparent background is not supported for this model."
Type: image_generation_user_error
Fires on: openai/gpt-image-2 (1.1s, before any generation)
Works on: openai/gpt-image-1.5 (200, RGBA PNG, 67.3% alpha-zero pixels)
Silent fail: gemini-3-pro-image, qwen-image-3.0, mai-image-2.5-flash
all 200, all colour type 2, no alpha channel
Format rule: PNG only. jpeg is a 400, webp is a 400.
Prompt rule: prompt beats parameter. Scene words put the scene back.
Measured: 2026-08-24, POST /v1/images/generations, 1024x1024, n=1
Three Fixes in Priority Order
Switch the model. The transparency capability is tied to the specific deployment, not the request parameters. Switching to a different model ID yields a 200 response with genuine alpha channel support.
Maintain PNG output format. Both
jpegandwebpformats return 400 errors, but for different reasons. JPEG cannot store alpha channels, while WebP is not supported by this endpoint at all.Rewrite the prompt. The prompt text carries more weight than the parameter setting. Prompts mentioning scenes, backgrounds, or specific environments result in opaque backgrounds despite the transparency parameter.
Last updated 2026-08-24. OpenAI describes transparent assets as preview functionality, so model capability availability may change. Re-test before relying on any model list.
Why Does gpt-image-2 Say Transparent Background Is Not Supported?
The deployment serving that model ID does not have the transparency preview feature enabled. The error message reflects an actual capability limitation, not a parameter syntax issue.
Complete error response:
{
"error": {
"code": null,
"message": "Transparent background is not supported for this model.",
"param": null,
"type": "image_generation_user_error"
}
}
Two critical details eliminate common explanations. The error arrives within 1.1 seconds—far too quickly for image generation and rejection. Additionally, the identical request with background: "opaque" returns 200 with a normal image on the same model using the same API key. This proves the parameter is reaching the provider and only the transparent value is rejected.
The widespread confusion stems from OpenAI's cookbook example being written against gpt-image-2. The documentation does mention requiring access to a transparency-capable image model, but many users miss this distinction between model name and actual feature availability.
Which Image Models Return Transparent PNGs?
Only one of five tested models successfully returned a transparent PNG.
| Model | HTTP | Latency | PNG Colour Type | Transparent Pixels |
|---|---|---|---|---|
openai/gpt-image-1.5 |
200 | 29.0s | 6, truecolour + alpha | 67.3% |
openai/gpt-image-2 |
400 | 1.1s | n/a | n/a |
google/gemini-3-pro-image |
200 | 25.8s | 2, no alpha | 0 |
bailian/qwen-image-3.0 |
200 | 49.7s | 2, no alpha | 0 |
microsoft/mai-image-2.5-flash |
200 | 15.4s | 2, no alpha | 0 |
The bottom three rows represent dangerous scenarios. A 400 error provides immediate feedback about what needs changing. A 200 response returning an opaque PNG silently passes validation checks, consumes generation credits, and appears as a white box in presentations days later.
Testing confirmed the behavior directly rather than inferring it. Sending background: "bogus" to gpt-image-1.5 returns a 400 error listing valid values:
Invalid value: 'bogus'. Supported values are: 'transparent', 'opaque', and 'auto'.
Sending identical invalid input to gemini-3-pro-image returns 200 with an image. A validating endpoint rejects garbage input; one accepting garbage was never going to honor transparent either.
Fix 1: Which Model to Switch To
Use openai/gpt-image-1.5—nothing else in the request requires modification. The body that fails on gpt-image-2 works unchanged:
from openai import OpenAI
client = OpenAI(base_url="https://api.ofox.ai/v1", api_key="YOUR_OFOX_API_KEY")
resp = client.images.generate(
model="openai/gpt-image-1.5", # gpt-image-2 returns 400 here
prompt=(
"A single glossy red ceramic coffee mug, isolated product cutout, "
"no backdrop, no scene, no shadow, no reflection, transparent background, "
"no text, no letters, no logos, no watermarks"
),
size="1024x1024",
background="transparent",
)
For catalog pipelines, explicitly specify the model ID and fail loudly when responses lack alpha channels rather than allowing fallback models to generate thousands of opaque cutouts silently.
Fix 2: Which Output Formats Support Alpha
Only PNG supports alpha channels on this endpoint. JPEG and WebP both return 400 errors:
output_format: "jpeg" -> 400 Transparent background is not supported for JPEG output format
output_format: "webp" -> 400 Invalid value: 'webp'. Supported values are: 'png' and 'jpeg'.
These represent different failure modes. The JPEG rejection reflects the format's inherent limitation—it cannot store transparency. The WebP rejection indicates this endpoint simply does not offer that format. For production pipelines, generate PNG files and convert downstream rather than requesting WebP directly.
Fix 3: Why Is Transparent Image Still Full of Background
The prompt parameter outweighs the API setting by a substantial margin. OpenAI's documentation mentions this; testing quantified the impact.
With identical model and background: "transparent" settings, two different prompts produced vastly different results:
| Prompt | Fully Transparent Pixels | Fully Opaque Pixels | Result |
|---|---|---|---|
| Isolated subject, "no backdrop, no scene, no shadow" | 67.3% | 24.1% | Clean cutout |
| "on a marble kitchen counter at sunrise, soft window light" | 43.5% | 21.7% | Mug, counter, window frame, sunrise sky knocked out |
The second image is not a feature failure—the transparency system worked as designed. It produced alpha around the scene explicitly requested in the prompt text, which proves useless for product catalogs and worse if unreviewed files enter production.
Practical guidance: describe only the object, then add negative constraints. Words like "counter," "studio," "gradient," "table," "sunset," and "shadow" reintroduce backgrounds. Reflections have the same effect.
How to Check PNG Transparency
Read a single byte. PNG stores colour type in the IHDR chunk at offset 25 in the file:
python3 -c "print('colour type', open('out.png','rb').read(26)[25])"
# 6 = truecolour + alpha 4 = greyscale + alpha
# 2 = truecolour, no alpha 3 = indexed (transparency may live in a tRNS chunk)
Colour type is necessary but insufficient. An RGBA file with alpha channel values of 255 everywhere is technically opaque despite having an alpha channel. Count pixels instead:
from PIL import Image
im = Image.open("out.png")
print(im.mode) # RGBA if an alpha channel exists
if im.mode == "RGBA":
hist = im.getchannel("A").histogram()
px = im.width * im.height
print(f"{100 * hist[0] / px:.1f}% fully transparent")
print(f"{100 * hist[255] / px:.1f}% fully opaque")
Every statistic in this article came from these two checks. Include alpha validation in CI pipelines. When a generation service silently switches which deployment backs a model ID, it will not announce the change; a test asserting "more than 30% of pixels are fully transparent" will catch it.
How to Test Multiple Image Models Without Multiple Accounts
The genuine difficulty is not the code—it is accessing five different vendor accounts, SDKs, and billing relationships simultaneously just to answer one yes-or-no question about a parameter.
All models in the comparison table respond to the same POST /v1/images/generations endpoint using the same API key because they are exposed through the OpenAI-compatible interface. The matrix exists because changing model= was the complete difference between rows. The tests ran through ofox, and any gateway that passes the field through rather than normalizing it will produce identical results. Verify this passthrough before trusting results: if background: "bogus" does not return 400, the route is not truthfully reporting the parameter state.
What If Your Required Model Lacks Transparency
When locked to a model that drops the field, three options exist: two honest approaches and one to avoid.
Generate on solid background and cut it out. A flat, unnatural background color absent from the subject makes downstream matting far simpler. Slower and lossy at edges, but predictable.
Generate once on a capable model and reuse. Transparency is a file property, not pipeline-dependent. One quality cutout beats repeated re-renders.
Do not ship the opaque 200 response. Unreviewed opaque images surface as white rectangles on colored slides, and by then the batch reaches thousands of files.
What Does One Transparent Image Cost
A successful 1024x1024 generation on gpt-image-1.5 billed 46 input tokens and 4,415 output tokens (4,160 image, 255 text). At published rates—$5 per million input, $32 per million output image, $10 per million output text—the cost is approximately $0.136 per cutout image.
One caveat: gpt-image-2 with background: "opaque" reported only 196 image output tokens for the same size. Different models reporting wildly different token counts per megapixel means pricing should derive from measured usage per model rather than assuming constant rates. The same principle applies to text models.
Frequently Asked Questions
Why does gpt-image-2 say transparent background is not supported?
Transparent image assets represent a preview feature gated per model deployment. The tested gpt-image-2 route lacks this capability. The same request with background: "opaque" or "auto" returns 200 on the same model, proving the parameter reaches the provider. Only the transparent value faces rejection in approximately 1.1 seconds—impossibly fast for post-generation rejection.
Which OpenAI image model supports background transparent?
On the tested route, openai/gpt-image-1.5 returns PNG with IHDR colour type 6 and 67.3% transparent pixels. OpenAI's cookbook uses gpt-image-2, explaining user surprise. The documentation states you need access to a transparency-capable model—access determines capability, not model name alone.
Can I get a transparent JPEG?
No. JPEG lacks alpha channel support, and the API rejects this combination up front with the error message. PNG remains the only option; output_format: "webp" returns an error stating that format is unsupported.
My call returned 200 but the PNG has white background. What happened?
The model likely never received the parameter. Three non-OpenAI image models tested with background: "transparent" all returned 200 with colour type 2 PNGs lacking alpha. One also accepted background: "bogus" and returned 200—the telltale sign a route drops the field entirely rather than validating it.
Why is there still background in my transparent image?
Prompt text outranks the parameter setting. Testing demonstrated the same model and background setting produced 67.3% transparent pixels with an isolated-subject prompt versus 43.5% with scene descriptions. Describe only the subject and specify "no backdrop, no scene, no shadow" in negatives.
How do I check PNG transparency really exists?
Read byte 25: 6 means truecolour with alpha, 2 means no alpha. Colour type 3 (indexed) may carry transparency in a separate chunk, treat as uncertain. Then count pixels at alpha zero, since an RGBA file with alpha entirely 255 is opaque despite having a channel.
Does an image gateway strip the background parameter?
Not on the tested route. gpt-image-2 accepted background: "opaque" and "auto" with 200 and rejected only transparent; gpt-image-1.5 rejected invalid value "bogus" with a 400 listing legal options. Both behaviors require the field reaching the provider.
How much does one transparent image cost?
A 1024x1024 transparent generation on gpt-image-1.5 billed 46 input and 4,415 output tokens (4,160 image). At published rates, approximately $0.136 per image.
Originally published on ofox.ai/blog.
Top comments (0)