openclaw/docs/providers/openai/image-and-video.md

Multi-channel AI gateway with extensible messaging integrations

---
summary: "Generate and edit images with OpenAI gpt-image"
read_when:
  - You are generating or editing images through the openai provider
  - You need transparent-background image output
title: "OpenAI image generation"
sidebarTitle: "Image generation"
---

## 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" } },
    },
  },
}
```

<Note>
See [Image Generation](/tools/image-generation) for shared tool parameters,
provider selection, and failover behavior.
</Note>

`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](/tools/video-generation) for supported providers.