openai-gpt-image

What it does

Guides production workflows for still-image tasks using OpenAI GPT Image models. It covers choosing between GPT Image 2 and legacy GPT Image variants, selecting Image API versus Responses API, crafting prompts and reference-image workflows, applying masks and multiple inputs, preserving identity/branding, rendering in-image text, handling output files and partial images, estimating cost and rate limits, migrating deprecated image code, and applying OpenAI image safety, consent, privacy, provenance, and rights requirements. It explicitly excludes video or audio tasks.

How it works

• Recommends starting with the current lifecycle and choosing the appropriate surface: Image API for a single operation or Responses API for a conversational workflow.
• Distinguishes model deployment: use gpt-image-2 as default, migrate from deprecated models (gpt-image-1, 1.5, 1-mini) per the lifecycle table.
• Specifies how to structure surface calls: Image API uses POST /v1/images/generations or POST /v1/images/edits; Responses API uses a mainline model with tool-level model set to gpt-image-2 and uses previous_response_id, image-generation call IDs, or file IDs to carry context.
• Defines output parameters and constraints: supports streaming partial images (0-3), each partial incurs 100 image output tokens; acceptable sizes and formats for gpt-image-2 with size, resolution, and quality guidance; image outputs default to PNG, with options for JPEG or WebP and corresponding compression.
• Describes inputs, masks, and fidelity: inputs may be PNG/WebP/JPEG; masks must be PNG with alpha channel and match input dimensions; masking is prompt-based for GPT Image; for multiple inputs, mask applies to the first image.
• Provides prompting guidance and structure for prompts as visual specifications and text handling, including how to test exact text via EXACT, verbatim, and how to stage iterations.
• Outlines a production decision checklist and validation steps to ensure rights, consent, and compliance prior to delivery.

When to use it

• Use when choosing between GPT Image 2 and legacy GPT Image/DALL-E integrations, and when deciding between Image API and Responses API.
• Use when building prompts, reference-image workflows, masks, multiple inputs, or preserving identity/brand details.
• Use when rendering in-image text, handling output files and partial images, or when estimating cost and rate limits.
• Use when migrating deprecated image code or applying OpenAI image safety, consent, privacy, provenance, and rights requirements.
• Do not use for OpenAI video or audio generation.

What it can touch

• Tools: claude-code, codex, copilot, cursor
• It references specific API surfaces and models (gpt-image-2, gpt-image-1, etc.), image endpoints (POST /v1/images/generations, POST /v1/images/edits), and streaming behavior. It specifies handling of inputs, outputs, and prompts but does not reveal external files beyond the described endpoints and inputs.

Caveats

• Contains production guidance and model lifecycle notes (e.g., deprecations and migration timelines) that are subject to change; recheck model pages, image guide, pricing, and deprecations before customer-facing work.
• Mentions that certain outputs (e.g., transparent backgrounds) are not supported by gpt-image-2 and that legacy endpoints for transparency are deprecated; verify current schema if conflicts arise.
• Includes performance and cost considerations such as partial image tokens and recommended sizes; exact costs are subject to current pricing.
• Some details reference external sources and are contingent on OpenAI API behavior and policies, which may change.