Image Generation and Editing with image_generate

The image_generate tool handles both image creation and editing through the providers you have set up. Inside chat sessions it works asynchronously: OpenClaw registers a background job, hands back the task id right away, and notifies the agent once the provider completes. The completion agent follows whatever visible-reply mode the session normally uses, delivering the final reply automatically when that is configured, or falling back to message(action="send") if the session needs the message tool. When the requesting session is not active, or when waking it fails, OpenClaw sends an idempotent direct fallback carrying the generated images so nothing gets lost.

Note

This tool shows up only when at least one image-generation provider is configured. If image_generate is missing from your agent's tool list, set up agents.defaults.mediaModels.image, add a provider API key, or authenticate through OpenAI ChatGPT/Codex OAuth.

Quick start

Configure auth

At least one provider needs an API key, for instance OPENAI_API_KEY, GEMINI_API_KEY, or OPENROUTER_API_KEY, or you can sign in with OpenAI Codex OAuth.

Pick a default model (optional)

{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openai/gpt-image-2",
        timeoutMs: 180_000,
      },
    },
  },
}

ChatGPT/Codex OAuth relies on the same openai/gpt-image-2 model ref. With an openai OAuth profile in place, OpenClaw sends image requests through that profile rather than attempting OPENAI_API_KEY first. Adding explicit models.providers.openai configuration, such as an API key or a custom/Azure base URL, switches back to the direct OpenAI Images API path.

Ask the agent

"Generate an image of a friendly robot mascot."

The agent invokes image_generate on its own. No allow-listing is required, it is on by default whenever a provider exists. The tool returns a background task id, and the completion agent later delivers the generated attachment through the message tool.

Warning

For OpenAI-compatible LAN endpoints like LocalAI, set the custom models.providers.openai.baseUrl and opt in explicitly with browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true. Private and internal image endpoints stay blocked unless you do so.

Common routes

Text-to-image and reference-image editing both go through this same tool. Pass image for a single reference or images when you have several. With Krea 2 models on fal, those references act as style references rather than edit inputs. Output hints a provider supports, such as quality, outputFormat, and background, get forwarded when available and are reported as ignored when the provider does not claim support. Built-in transparent-background handling is exclusive to OpenAI; other providers may still keep PNG alpha if their backend produces it.

For text-to-image generation and reference-image edits, OpenAI supports low and auto moderation through the direct Images API or the Codex Responses backend. On CLI requests, pass --openai-moderation low|auto to either openclaw infer image generate or openclaw infer image edit.

Supported providers

At runtime, call action: "list" to see which providers and models are currently available:

/tool image_generate action=list

To check the active image-generation task for the current session, use action: "status":

/tool image_generate action=status

Provider capabilities

Tool parameters

• prompt (string, required), The prompt that drives image generation. Mandatory for action: "generate".

• action (generate" | "status" | "list, default: generate), For inspecting the active session task, call "status"; to enumerate providers and models at runtime, use "list".

• model (string), Override for the provider or model, for instance openai/gpt-image-2. Transparent OpenAI backgrounds are achieved with openai/gpt-image-1.5.

• image (string), A single path or URL pointing to the reference image in edit mode.

• images (string[]), Multiple reference images for edit mode or style-reference models. The shared tool caps this at 14, though provider-specific limits still apply.

• size (string), Size hint options: 1024x1024, 1536x1024, 1024x1536, 2048x2048, 3840x2160.

• aspectRatio (string), Aspect ratio: 1:1, 2:1, 20:9, 19.5:9, 2:3, 3:2, 2.35:1, 3:4, 4:3, 4:5, 5:4, 9:16, 9:19.5, 9:20, 16:9, 21:9, 1:2, 4:1, 1:4, 8:1, 1:8. Each provider checks the list against its own supported set.

• resolution (1K" | "2K" | "4K), Suggests the resolution level.

• quality (low" | "medium" | "high" | "auto), Quality preference, applied when the provider accepts it.

• outputFormat (png" | "jpeg" | "webp), Format preference, applied when the provider accepts it.

• background (transparent" | "opaque" | "auto), Background preference, applied when the provider accepts it. For providers that handle transparency, pair transparent with outputFormat: "png" or "webp".

• count (number), How many images to produce (1-4).

• timeoutMs (number), Optional per-request timeout in milliseconds. When Codex invokes image_generate through dynamic tools, this value overrides the configured default for that call and is limited to 600000 ms.

• filename (string), Suggested name for the output file.

• openai (object), OpenAI-specific options: background, moderation, outputCompression, and user.

• fal.creativity (raw" | "low" | "medium" | "high), fal Krea 2 creativity setting. Falls back to medium when not specified.

Note

Parameter support varies by provider. When a fallback provider offers a nearby geometry option rather than the exact one requested, OpenClaw adjusts to the closest supported size, aspect ratio, or resolution before sending. Output hints that a provider does not declare are ignored and mentioned in the tool result. The tool result lists the settings that were applied; details.normalization records any requested-to-applied mapping.

Configuration

Model selection

{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openai/gpt-image-2",
        timeoutMs: 180_000,
        fallbacks: [
          "openrouter/google/gemini-3.1-flash-image-preview",
          "google/gemini-3.1-flash-image",
          "fal/fal-ai/flux/dev",
        ],
      },
    },
  },
}

Provider selection order

OpenClaw checks providers in this sequence:

1. model parameter from the tool call (when the agent provides one).
2. imageGenerationModel.primary from config.
3. imageGenerationModel.fallbacks in order.
4. Auto-detection - only auth-backed provider defaults:
   • the current default provider first;
   • the remaining registered image-generation providers sorted by provider-id.

When a provider fails (auth error, rate limit, etc.), the next configured candidate is attempted automatically. If every candidate fails, the error carries details from each attempt.

Per-call model overrides are exact

A per-call model override targets only that provider/model and does not proceed to configured primary/fallback or auto-detected providers.

Auto-detection is auth-aware

A provider default enters the candidate list only when OpenClaw can authenticate that provider. Automatic fallback across authenticated providers is always on; a per-call model stays authoritative.

Timeouts

Set agents.defaults.mediaModels.image.timeoutMs for slow image backends. A per-call timeoutMs tool parameter overrides the configured default, and configured defaults override plugin-authored provider defaults. Google and OpenRouter hosted image providers use 180 second defaults; Microsoft Foundry MAI, xAI, and Azure OpenAI image generation use 600 seconds. Codex dynamic-tool calls use a 120 second image_generate bridge default and honor the same timeout budget when configured, bounded by OpenClaw's 600000 ms dynamic-tool bridge maximum.

Inspect at runtime

Use action: "list" to see the currently registered providers, their default models, and auth env-var hints.

Image editing

OpenAI, OpenRouter, Google, DeepInfra, fal, Microsoft Foundry, MiniMax, ComfyUI, and xAI all accept reference images for editing. On fal, Krea 2 models rely on the same image / images fields used for style references rather than dedicated edit inputs. Provide either a path or URL to the reference image:

"Generate a watercolor version of this photo" + image: "/path/to/photo.jpg"

Via the images parameter, OpenAI, OpenRouter, and Google allow up to 5 reference images; xAI permits up to 3. For fal, Flux image-to-image takes 1 reference image, GPT Image 2 edits accept up to 10, Krea 2 style references support up to 10, and Nano Banana 2 edits handle up to 14. Microsoft Foundry, MiniMax, and ComfyUI each support 1.

Provider deep dives

OpenAI gpt-image-2 (and gpt-image-1.5)

By default, OpenAI image generation uses openai/gpt-image-2. When an openai OAuth profile is set up, OpenClaw reuses the OAuth profile that Codex subscription chat models employ and dispatches the image request through the Codex Responses backend. Legacy Codex base URLs like https://chatgpt.com/backend-api get canonicalized to https://chatgpt.com/backend-api/codex for image requests. OpenClaw will not quietly switch to OPENAI_API_KEY for that request; to force direct routing to the OpenAI Images API, set models.providers.openai explicitly with an API key, a custom base URL, or an Azure endpoint.

The openai/gpt-image-1.5, openai/gpt-image-1, and openai/gpt-image-1-mini models remain selectable explicitly. For transparent-background PNG/WebP output, use gpt-image-1.5; the current gpt-image-2 API rejects background: "transparent".

Both text-to-image generation and reference-image editing are handled by gpt-image-2 through the same image_generate tool. OpenClaw passes prompt, count, size, quality, outputFormat, and reference images along to OpenAI. Neither aspectRatio nor resolution is sent directly to OpenAI; where possible OpenClaw converts those into a supported size, otherwise the tool flags them as ignored overrides.

For requests going straight to the OpenAI Images API, gpt-image-2 and its gpt-image-2-2026-04-21 snapshot keep valid explicit WIDTHxHEIGHT sizes intact rather than forcing them to presets. Each dimension must be a multiple of 16, neither can exceed 3840 pixels, the aspect ratio is capped at 3:1, and total pixels must fall between 655,360 and 8,294,400. As an example, 1024x640 qualifies. If only aspectRatio is given, OpenClaw picks the nearest supported size anyway.

OpenAI-specific settings reside within the openai object:

{
  "quality": "low",
  "outputFormat": "jpeg",
  "openai": {
    "background": "opaque",
    "moderation": "low",
    "outputCompression": 60,
    "user": "end-user-42"
  }
}

openai.background takes transparent, opaque, or auto; transparent output calls for outputFormat png or webp along with an OpenAI image model that supports transparency. Requests for transparent backgrounds using the default gpt-image-2 are routed by OpenClaw to gpt-image-1.5. openai.outputCompression affects JPEG/WebP output only and has no effect on PNG output.

The provider-neutral top-level background hint currently maps to the same OpenAI background request field when the OpenAI provider is in use. Providers that do not advertise background support report it in ignoredOverrides instead of getting the unsupported parameter.

To send OpenAI image generation through an Azure OpenAI deployment rather than api.openai.com, refer to Azure OpenAI endpoints.

Microsoft Foundry MAI image models

Microsoft Foundry image generation relies on deployed MAI image deployment names under the microsoft-foundry/ provider prefix. No provider-level default model exists because the MAI API requires your deployment name inside the model field:

{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "microsoft-foundry/<deployment-name>",
        timeoutMs: 600_000,
      },
    },
  },
}

This provider talks to Microsoft Foundry's MAI API, not the OpenAI Images API.

• Generation endpoint: /mai/v1/images/generations
• Edit endpoint: /mai/v1/images/edits
• Auth: AZURE_OPENAI_API_KEY / provider API key, or Entra ID through az login
• Output: one PNG image
• Size: default 1024x1024; width and height must each be at least 768 px, and total pixels must be at most 1,048,576
• Edits: one PNG or JPEG reference image, supported only by MAI-Image-2.5-Flash and MAI-Image-2.5 deployments

When generating from a prompt alone, a custom deployment name works with just the Foundry endpoint configured. For edits using custom deployment names, onboarding and model metadata are required so OpenClaw can confirm the deployment is based on MAI-Image-2.5-Flash or MAI-Image-2.5.

The current MAI image models are MAI-Image-2.5-Flash, MAI-Image-2.5, MAI-Image-2e, and MAI-Image-2. Refer to the Microsoft Foundry plugin for configuration details and chat-model behavior.

OpenRouter image models

OpenRouter image generation relies on the same OPENROUTER_API_KEY and goes through OpenRouter's chat completions image API. Choose OpenRouter image models by using the openrouter/ prefix:

{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openrouter/google/gemini-3.1-flash-image-preview",
      },
    },
  },
}

OpenClaw sends prompt, count, reference images, and Gemini-compatible aspectRatio / resolution hints to OpenRouter. Built-in OpenRouter image model shortcuts currently include google/gemini-3.1-flash-image, google/gemini-3-pro-image, and openai/gpt-5.4-image-2. Run action: "list" to see what your configured plugin exposes.

fal Krea 2

Krea 2 models on fal adopt fal's native Krea schema rather than the generic image_size schema used by Flux. OpenClaw transmits:

• aspect_ratio for aspect-ratio hints
• creativity, which defaults to medium
• image_style_references when image or images are provided

Pick Krea 2 Medium for quicker expressive illustration and Krea 2 Large for slower, more detailed photoreal and textured results:

{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "fal/krea/v2/medium/text-to-image",
      },
    },
  },
}

Krea 2 returns a single image per request at present. For Krea, prefer aspectRatio; OpenClaw converts size to the nearest supported Krea aspect ratio and rejects resolution for Krea instead of ignoring it. Use fal.creativity when you need a native Krea creativity level:

{
  "model": "fal/krea/v2/medium/text-to-image",
  "prompt": "A cyber zine portrait with risograph texture",
  "aspectRatio": "9:16",
  "fal": {
    "creativity": "high"
  }
}

MiniMax dual-auth

MiniMax image generation works with both bundled MiniMax auth paths:

• minimax/image-01 for API-key setups
• minimax-portal/image-01 for OAuth setups

xAI grok-imagine-image

The bundled xAI provider uses /v1/images/generations for prompt-only requests and /v1/images/edits when image or images is present.

• Models: xai/grok-imagine-image, xai/grok-imagine-image-quality
• Count: max 4
• References: a single image or as many as three images
• Aspect ratios: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 2:1, 1:2, 19.5:9, 9:19.5, 20:9, 9:20
• Resolutions: 1K, 2K
• Outputs: delivered as image attachments managed by OpenClaw

Until the shared cross-provider image_generate contract includes them, OpenClaw deliberately withholds xAI's native quality, mask, user, and the auto aspect ratio.

Examples

Generate (4K landscape)

/tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1

Generate (transparent PNG)

/tool image_generate action=generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent

CLI equivalent:

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

Generate (OpenAI low quality)

/tool image_generate action=generate model=openai/gpt-image-2 prompt="Low-cost draft poster for a quiet productivity app" quality=low openai='{"moderation":"low"}'

CLI equivalent:

openclaw infer image generate \
  --model openai/gpt-image-2 \
  --quality low \
  --openai-moderation low \
  --prompt "Low-cost draft poster for a quiet productivity app" \
  --json

Generate (two square)

/tool image_generate action=generate model=openai/gpt-image-2 prompt="Two visual directions for a calm productivity app icon" size=1024x1024 count=2

Edit (one reference)

/tool image_generate action=generate model=openai/gpt-image-2 prompt="Keep the subject, replace the background with a bright studio setup" image=/path/to/reference.png size=1024x1536

Edit (multiple references)

/tool image_generate action=generate model=openai/gpt-image-2 prompt="Combine the character identity from the first image with the color palette from the second" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024

Krea style references

/tool image_generate action=generate model=fal/krea/v2/medium/text-to-image prompt="An expressive editorial portrait using this color palette and print texture" images='["/path/to/palette.png","/path/to/texture.jpg"]' aspectRatio=9:16 fal='{"creativity":"high"}'

The flags --output-format, --background, and --quality work the same way on openclaw infer image edit; --openai-background continues to serve as an OpenAI-only alias. For both OpenAI image generation and reference-image edits, apply --openai-moderation low|auto. The moderation hint is supported by the direct OpenAI Images API as well as the ChatGPT/Codex OAuth Responses backend. Since bundled providers other than OpenAI currently offer no explicit background control, background: "transparent" is flagged as ignored for them.

Related

• Tools overview - every tool available to agents
• ComfyUI - configuring local ComfyUI and Comfy Cloud workflows
• fal - setting up fal for image and video
• Google (Gemini) - configuring Gemini as the image provider
• Microsoft Foundry plugin - Microsoft Foundry chat and MAI image configuration
• MiniMax - configuring MiniMax as the image provider
• OpenAI - configuring the OpenAI Images provider
• Vydra - Vydra setup for image, video, and speech
• xAI - Grok setup for image, video, search, code execution, and TTS
• Configuration reference - imageGenerationModel configuration
• Models - model configuration and failover handling