# OpenAI image generation > Generate and edit images with OpenAI gpt-image - 网址：https://funcoding.ai/agents/openclaw/providers/openai/image-and-video/ - 来源：OpenClaw 官方文档原文（英文），MIT 许可，同步于 2026-10-11 - 官方原文：https://docs.openclaw.ai/zh-CN/providers/openai/image-and-video --- ## Image generation The bundled `openai` plugin registers image generation through the `image_generate` tool. It supports both OpenAI API-key and Codex OAuth image generation through the same `openai/gpt-image-2` model ref. Sign in with ChatGPT (SIWC) cannot authorize this tool. Codex OAuth here means an OpenClaw model auth profile; signing in only to a native Codex user home does not supply `image_generate` with a credential. | Capability | OpenAI API key | Codex OAuth | | ------------------------- | ---------------------------------- | ------------------------------------ | | Model ref | `openai/gpt-image-2` | `openai/gpt-image-2` | | Auth | `OPENAI_API_KEY` | OpenAI Codex OAuth sign-in | | Transport | OpenAI Images API | Codex Responses backend | | Max images per request | 4 | 4 | | Edit mode | Enabled (up to 5 reference images) | Enabled (up to 5 reference images) | | Moderation | `low` or `auto`; generate and edit | `low` or `auto`; generate and edit | | Size overrides | Supported, including 2K/4K sizes | Supported, including 2K/4K sizes | | Aspect ratio / resolution | Not forwarded to OpenAI Images API | Mapped to a supported size when safe | ```json5 { agents: { defaults: { mediaModels: { image: { primary: "openai/gpt-image-2" } }, }, }, } ```
See [Image Generation](https://funcoding.ai/agents/openclaw/tools/image-generation/) for shared tool parameters, provider selection, and failover behavior.
`gpt-image-2` is the default for OpenAI text-to-image generation and image editing. `gpt-image-1.5`, `gpt-image-1`, and `gpt-image-1-mini` remain usable as explicit model overrides. Use `openai/gpt-image-1.5` for transparent-background PNG/WebP output; the current `gpt-image-2` API rejects `background: "transparent"`. ### GPT Image 2.5 Select `openai/gpt-image-2.5-flare` or `openai/gpt-image-2.5-sunburst` explicitly. Both support generation and edits through the direct Images API. The default remains `openai/gpt-image-2`. Export `OPENAI_API_KEY` and select API-key authentication: ```json5 { models: { providers: { openai: { baseUrl: "https://api.openai.com/v1", auth: "api-key", models: [], }, }, }, } ``` This explicit selection matters when an OpenAI OAuth profile also exists. Exporting the environment variable alone does not override that profile. GPT Image 2.5 subscription access is not established by this API-key setup. Both variants accept `low`, `medium`, `high`, `xhigh`, `max`, or `auto` quality. Use PNG or WebP for transparent backgrounds. Edits accept up to 5 reference images through OpenClaw. ```bash openclaw infer image generate \ --model openai/gpt-image-2.5-flare \ --prompt "A simple red circle sticker on a transparent background" \ --quality low --output-format webp --background transparent --json openclaw infer image edit \ --model openai/gpt-image-2.5-sunburst \ --file /path/to/reference.png \ --prompt "Keep the shape and change the color to blue" \ --quality low --size auto --json ``` `size` accepts `auto` or `WIDTHxHEIGHT`. Dimensions must be divisible by 16, with no edge above 3840 pixels and total pixels between 655,360 and 8,294,400. The aspect ratio must be between 1:3 and 3:1. ### Other Image Models For a transparent-background request, call `image_generate` with `model: "openai/gpt-image-1.5"`, `outputFormat: "png"` or `"webp"`, and `background: "transparent"`; the older `openai.background` provider option is still accepted. OpenClaw also protects the public OpenAI and OpenAI Codex OAuth routes by rewriting default `openai/gpt-image-2` transparent requests to `gpt-image-1.5`; Azure and custom OpenAI-compatible endpoints keep their configured deployment/model names. The same setting is exposed for headless CLI runs: ```bash openclaw infer image generate \ --model openai/gpt-image-1.5 \ --output-format png \ --background transparent \ --prompt "A simple red circle sticker on a transparent background" \ --json ``` Use the same `--output-format` and `--background` flags with `openclaw infer image edit` when starting from an input file. `--openai-background` remains available as an OpenAI-specific alias. Use `--quality low|medium|high|auto` to control OpenAI Images quality and cost. Use `--openai-moderation low|auto` with both `image generate` and `image edit` to pass OpenAI's moderation hint. The direct OpenAI Images API and the ChatGPT/Codex OAuth Responses backend both support moderation for text-to-image generation and reference-image edits. For ChatGPT/Codex OAuth installs, keep the same `openai/gpt-image-2` ref. When an `openai` OAuth profile is configured, OpenClaw resolves that stored OAuth access token and sends image requests through the Codex Responses backend; it does not first try `OPENAI_API_KEY` or silently fall back to an API key. That Responses request runs on `gpt-6-astra`. If your ChatGPT plan rejects that model, OpenClaw retries with each `openai/*` model in `agents.defaults.model` (primary, then fallbacks), so configure a model your plan supports there. Configure `models.providers.openai` explicitly with an API key, custom base URL, or Azure endpoint when you want the direct OpenAI Images API route instead. If that custom image endpoint is on a trusted LAN/private address, also set `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`; OpenClaw keeps private/internal OpenAI-compatible image endpoints blocked unless this opt-in is present. Generate: ``` /tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1 ``` Generate a transparent PNG: ``` /tool image_generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent ``` Edit: ``` /tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536 ``` OpenAI retired its Sora video API on 2026-09-24; see [Video generation](https://funcoding.ai/agents/openclaw/tools/video-generation/) for supported providers.