{"record":{"id":"7505976b97d26c0b","repo":"Comfy-Org/ComfyUI","slug":"transparent-background-is-not-supported-for-gpt-im","errorCode":null,"errorMessage":"Transparent background is not supported for GPT Image 2 model","messagePattern":"Transparent background is not supported for GPT Image 2 model","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy_api_nodes/nodes_openai.py","lineNumber":562,"sourceCode":"                raise ValueError(f\"Custom resolution max edge must be <= 3840, got {custom_width}x{custom_height}\")\n            ratio = max(custom_width, custom_height) / min(custom_width, custom_height)\n            if ratio > 3:\n                raise ValueError(\n                    f\"Custom resolution aspect ratio must not exceed 3:1, got {custom_width}x{custom_height}\"\n                )\n            total_pixels = custom_width * custom_height\n            if not 655_360 <= total_pixels <= 8_294_400:\n                raise ValueError(\n                    f\"Custom resolution total pixels must be between 655,360 and 8,294,400, got {total_pixels}\"\n                )\n            size = f\"{custom_width}x{custom_height}\"\n        elif model in (\"gpt-image-1\", \"gpt-image-1.5\"):\n            if size not in (\"auto\", \"1024x1024\", \"1024x1536\", \"1536x1024\"):\n                raise ValueError(f\"Resolution {size} is only supported by GPT Image 2 model\")\n\n        if model == \"gpt-image-2\":\n            if background == \"transparent\":\n                raise ValueError(\"Transparent background is not supported for GPT Image 2 model\")\n        elif model not in (\"gpt-image-1\", \"gpt-image-1.5\"):\n            raise ValueError(f\"Unknown model: {model}\")\n\n        if image is not None:\n            files = []\n            batch_size = image.shape[0]\n            for i in range(batch_size):\n                single_image = image[i : i + 1]\n                scaled_image = downscale_image_tensor(single_image, total_pixels=2048 * 2048).squeeze()\n\n                image_np = (scaled_image.numpy() * 255).astype(np.uint8)\n                img = Image.fromarray(image_np)\n                img_byte_arr = BytesIO()\n                img.save(img_byte_arr, format=\"PNG\")\n                img_byte_arr.seek(0)\n\n                if batch_size == 1:\n                    files.append((\"image\", (f\"image_{i}.png\", img_byte_arr, \"image/png\")))","sourceCodeStart":544,"sourceCodeEnd":580,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy_api_nodes/nodes_openai.py#L544-L580","documentation":"Client-side ValueError: background='transparent' was requested with model='gpt-image-2'. GPT Image 2 does not support transparent background output (unlike gpt-image-1), so the node rejects the combination instead of letting the API fail opaquely.","triggerScenarios":"model='gpt-image-2' with the background widget set to 'transparent' in the OpenAI image node.","commonSituations":"Copying gpt-image-1 workflows and only changing the model; compositing workflows that assume alpha output is always available.","solutions":["Set background to 'opaque' (or 'auto') for gpt-image-2","If you need transparency, use gpt-image-1/1.5 which accept background='transparent'","For GPT Image 2 results, remove the background in post (rembg or a matting node)"],"exampleFix":"// before\nmodel=\"gpt-image-2\", background=\"transparent\"\n// after\nmodel=\"gpt-image-2\", background=\"opaque\"\n// or switch model:\nmodel=\"gpt-image-1\", background=\"transparent\"","handlingStrategy":"validation","validationCode":"if model == \"gpt-image-2\":\n    assert background != \"transparent\", \"gpt-image-2 cannot output transparency\"","typeGuard":"def background_valid(model: str, background: str) -> bool:\n    return not (model == \"gpt-image-2\" and background == \"transparent\")","tryCatchPattern":null,"preventionTips":["Remember transparency belongs to gpt-image-1/1.5 only","Reset background to opaque/auto when switching to gpt-image-2","Plan a post-generation matting step if you need alpha from gpt-image-2"],"tags":["openai","gpt-image","transparency","validation"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}