DALL-E API (gpt-image models)

Overview

DALL-E 2 and DALL-E 3 were shut down on 2026-05-12. OpenAI's deprecations page lists both as removed from the API and recommends gpt-image-2, gpt-image-1 or gpt-image-1-mini instead. Code that passes model="dall-e-3" or "dall-e-2" no longer works, and variations (a DALL-E 2 feature) have no gpt-image equivalent. The endpoints are the same: images.generate (/v1/images/generations) and images.edit (/v1/images/edits).

Key differences from DALL-E: gpt-image models always return base64 (data[0].b64_json), never URLs; they do not return revised_prompt; style, response_format are not supported; edits take multiple input images and a prompt-guided mask. OpenAI's reference also lists newer gpt-image-1.5 and gpt-image-2.5-sunburst / gpt-image-2.5-flare models; check the model list in the reference before pinning one. This skill uses gpt-image-2.

Instructions

Step 1: Client

pip install openai
export OPENAI_API_KEY="..."   # set in your shell or secret manager

import base64
from pathlib import Path
from openai import OpenAI

client = OpenAI()  # reads OPENAI_API_KEY
MODEL = "gpt-image-2"

def save(response, path: str, index: int = 0) -> str:
    Path(path).write_bytes(base64.b64decode(response.data[index].b64_json))
    return path

Step 2: Generate

res = client.images.generate(
    model=MODEL,
    prompt="A ceramic mug with steam rising on a marble kitchen counter, warm morning light, 50mm photo",
    size="1536x1024",
    quality="medium",
    output_format="webp",
    output_compression=85,
)
save(res, "mug.webp")
print(res.usage)  # token counts, use them to measure cost

Parameters (verified against the API reference):

Step 3: Edit with a mask or several images

# Mask edit: fully transparent pixels in the mask mark where to change.
with open("living-room.png", "rb") as img, open("sofa-mask.png", "rb") as mask:
    res = client.images.edit(
        model=MODEL,
        image=img,
        mask=mask,
        prompt="Replace the sofa with a dark green velvet sofa, keep everything else",
    )
save(res, "living-room-green.png")

# Combine several reference images (up to 16, each PNG/WebP/JPG under 50MB).
files = [open(p, "rb") for p in ("lotion.png", "soap.png", "candle.png")]
res = client.images.edit(
    model=MODEL,
    image=files,
    prompt="A gift basket product shot with all three items on a linen cloth",
)
for f in files:
    f.close()
save(res, "gift-basket.png")

Mask rules: PNG under 4MB, same dimensions as the image, must have an alpha channel; with several images the mask applies to the first. Masking is prompt-guided, so the model may not follow the exact outline. input_fidelity (high/low) exists for gpt-image-1 style models (gpt-image-1-mini supports only low); omit it for gpt-image-2.

To build a mask with Pillow: open the image as RGBA, create a same-size opaque image, and set alpha to 0 where edits should happen.

Step 4: Handle errors and moderation

A blocked request fails with error code moderation_blocked; moderation_details carries categories and moderation_stage (input means revise the prompt or input images, output means change the prompt and retry). Wrap calls with retry and backoff for rate limits (limits depend on your usage tier; see the Limits page of your account).

Migration from DALL-E 3

Examples

Example 1: "Hero image for our electric-car landing page"

res = client.images.generate(
    model="gpt-image-2",
    prompt="A sleek electric car driving through a futuristic city at night, neon reflections on wet streets, cinematic",
    size="1536x1024", quality="high",
)
save(res, "electric_car.png")

Result: a 1536x1024 PNG on disk; res.usage shows the input and output tokens used.

Example 2: "Swap the background behind our product photo for a beach"

Make background-mask.png with transparent pixels over the background, then:

with open("product.png", "rb") as img, open("background-mask.png", "rb") as mask:
    res = client.images.edit(model="gpt-image-2", image=img, mask=mask,
        prompt="A tropical beach at sunset behind the product; do not change the product")
save(res, "product_beach.png")

Result: product_beach.png with the masked area regenerated.

Example 3: "A logo sticker with a transparent background"

res = client.images.generate(model="gpt-image-2", prompt="Flat vector fox logo sticker, white outline",
    background="transparent", output_format="png")
save(res, "fox.png")

Guidelines

• Pricing is token-based, not per image: cost depends on model, quality and size. Read res.usage to measure real cost, and use low/medium quality for drafts. For the current per-token rates see the OpenAI pricing page.
• Never rely on image URLs; decode b64_json and store the file yourself.
• Pin an explicit model name; do not rely on defaults.
• Keep the API key in an environment variable and never log it.
• For Azure-hosted deployments or general OpenAI SDK usage, see the azure-openai and openai-sdk skills.