gpt-image

name	gpt-image
description	OpenAI image API workflows: use when a task needs provider discovery, `gpt-image-2` request construction, text-to-image generation, reference-image edits, or OpenAI-compatible gateway handling outside a built-in image tool.

GPT Image

Use this skill when image work should go through an OpenAI API or an OpenAI-compatible gateway rather than a host-native image tool.

Workflow

1. Re-check current official OpenAI image docs before writing production code or making claims about supported parameters, models, or tool behavior:
   • https://developers.openai.com/api/docs/guides/image-generation
   • https://developers.openai.com/api/reference/resources/images/methods/generate
   • https://developers.openai.com/api/reference/resources/images/methods/edit
   • https://developers.openai.com/api/reference/resources/images/methods/create_variation
2. Read references/provider-discovery.md when the API key, base URL, model routing, or gateway capabilities are not already explicit.
3. Read references/api-reference.md when you need the compact endpoint map, request examples, or current parameter caveats.
4. Resolve the target in this order:
   • explicit user-supplied model, key, or base URL
   • existing project code and config such as OPENAI_API_KEY, OPENAI_BASE_URL, baseURL, base_url, and OpenAI client initialization
   • host-specific agent settings only if the current host is known to expose OpenAI provider configuration
   • official default base URL https://api.openai.com/v1
5. Choose one API path and avoid speculative fallback branches:
   • POST /v1/images/generations for text-to-image generation
   • POST /v1/images/edits for edits, masks, or reference-image workflows when the target documents support it
   • POST /v1/responses with the image_generation tool for conversational or multi-turn image work only when current model docs confirm support
   • never use POST /v1/images/variations for gpt-image-2
6. Use the least expensive capability check that answers the question:
   • inspect local config, code, and docs first
   • if live verification is needed, start with GET /v1/models
   • only run billable image requests when the user intends to spend credits
7. Build explicit request bodies:
   • always set model: "gpt-image-2" for Images API requests
   • default to png, n: 1, and standard sizes before trying custom shapes
   • treat transparent backgrounds, custom sizes, streaming, and gateway-only fields as opt-in only after the current docs confirm support
   • omit input_fidelity for official gpt-image-2 edit requests
8. Use the bundled script for repeatable checks and guarded request building:
   • python scripts/gpt_image_2_tool.py discover
   • python scripts/gpt_image_2_tool.py model-check
   • python scripts/gpt_image_2_tool.py request-json --prompt "..."
   • python scripts/gpt_image_2_tool.py generate ...
   • python scripts/gpt_image_2_tool.py responses-request-json ...
   • python scripts/gpt_image_2_tool.py responses-edit ...
9. Parse official GPT image responses from data[].b64_json and write bytes with the requested extension. For Responses tool output, read image_generation_call.result.
10. Do not add vendor-name branches, undocumented defaults, or compatibility code unless the user explicitly asks for them.

Default Request Shape

{
  "model": "gpt-image-2",
  "prompt": "A concise, structured image specification.",
  "size": "1536x1024",
  "quality": "auto",
  "output_format": "png"
}

Use 1024x1024 for square assets and fast iteration. Use 1536x1024 or 1024x1536 for landscape or portrait outputs. For high-resolution requests, re-check current official limits first.

Prompt Shape

For generation prompts, structure the prompt in this order:

1. Purpose and output type.
2. Scene or background.
3. Main subject.
4. Required visual details.
5. Style, medium, camera, or composition constraints.
6. Hard constraints and avoid list.

If a provider-supported edit workflow has been confirmed, explicitly separate:

• Change: what should be altered or created.
• Preserve: subject identity, composition, camera angle, proportions, palette, style, and any other elements that must stay stable.
• Avoid: extra objects, changed identity, changed viewpoint, text artifacts, or unwanted background changes.

Use concrete visual nouns and constraints. Do not rely on vague terms such as beautiful, premium, or high quality without specifying materials, layout, texture, lighting, and composition.

Implementation Notes

• Prefer official SDK helpers when the existing project already uses the OpenAI SDK. Match the project's SDK version and patterns.
• Use responses-request-json when you need a redacted preview of a Responses image-edit body with local reference images converted to safe placeholders instead of raw base64.
• Use responses-edit when the target documents image_generation action="edit" support and the task genuinely needs a Responses flow.
• By default, generated files should land in the project-local .imagegen/outputs/ directory unless the caller explicitly chooses another --out-dir.
• Use --max-time <seconds> on billable HTTP commands when the configured provider is known to run slowly or when you want a tighter failure bound for live probes.
• When probing an OpenAI-compatible gateway, prefer a stable explicit User-Agent instead of the Python stdlib default. If a request still fails with a gateway-style block such as HTTP 403 plus an edge/firewall code, retry with a small predefined header profile set before treating the target as unavailable.
• For local image inputs, use the provider's documented edit shape exactly. For the official OpenAI API, raw HTTP edit requests use multipart image[] uploads, while SDKs may present the same flow as image=[...]. Omit input_fidelity because gpt-image-2 already processes input images at high fidelity.
• When adding code, include focused tests around request construction and response parsing. Mock network calls; do not spend image-generation credits in unit tests.

References

• Provider discovery and safe config checks: references/provider-discovery.md
• Endpoint and parameter reference: references/api-reference.md