OpenAI 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.

{
  agents: {
    defaults: {
      mediaModels: { image: { primary: "openai/gpt-image-2" } },
    },
  },
}

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:

{
  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.

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:

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 for supported providers.