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

Auto-detection considers provider defaults whose readiness or auth checks pass.
Explicit image model configuration limits fallback to the configured list.
Apus does not append auto-detected providers.

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 Apus's 600000 ms dynamic-tool bridge maximum.

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

Select either variant explicitly. Existing provider defaults do not change:

- OpenAI: `openai/gpt-image-2.5-flare` or `openai/gpt-image-2.5-sunburst`
- fal: `fal/openai/gpt-image-2.5/flare/text-to-image` or
  `fal/openai/gpt-image-2.5/sunburst/text-to-image`

Both variants support generation, edits, `xhigh` and `max` quality,
PNG/JPEG/WebP output, and transparent backgrounds with PNG or WebP.
OpenAI accepts up to 5 reference images through Apus. fal accepts 16.
With reference images, fal replaces `/text-to-image` with `/edit`.
Explicit fal `/edit` paths remain unchanged.

Use the [explicit OpenAI API-key route](/providers/openai/image-and-video#gpt-image-2.5)
for direct GPT Image 2.5 requests. Exporting `OPENAI_API_KEY` alone does not
override an existing OAuth profile. These examples do not establish
GPT Image 2.5 subscription access.

Use `size: "auto"` or valid `WIDTHxHEIGHT` dimensions. Both dimensions
must be divisible by 16, with no edge above 3840 pixels.
Total pixels must be 655,360-8,294,400, with an aspect ratio from 1:3 to 3:1.
fal converts aspect-ratio hints to valid dimensions, such as `3:2` to
`1536x1024`. Invalid explicit sizes fail with a size error. fal does not accept
`resolution` overrides for these models or infer resolution from edit inputs.

OpenAI image generation defaults to `openai/gpt-image-2`. If an
`openai` OAuth profile is configured, Apus reuses the same
OAuth profile used by Codex subscription chat models and sends the
image request through the Codex Responses backend. Legacy Codex base
URLs such as `https://chatgpt.com/backend-api` are canonicalized to
`https://chatgpt.com/backend-api/codex` for image requests. Apus
does **not** silently fall back to `OPENAI_API_KEY` for that request -
to force direct OpenAI Images API routing, configure
`models.providers.openai` explicitly with an API key, custom base URL,
or Azure endpoint.

The `openai/gpt-image-1.5`, `openai/gpt-image-1`, and
`openai/gpt-image-1-mini` models can still be selected explicitly. Use
`gpt-image-1.5` for transparent-background PNG/WebP output. The current
`gpt-image-2` API rejects `background: "transparent"`.

`gpt-image-2` supports both text-to-image generation and
reference-image editing through the same `image_generate` tool.
Apus forwards `prompt`, `count`, `size`, `quality`, `outputFormat`,
and reference images to OpenAI. OpenAI does **not** receive
`aspectRatio` or `resolution` directly. When possible Apus maps
those into a supported `size`, otherwise the tool reports them as
ignored overrides.

For direct OpenAI Images API requests, `gpt-image-2` and its
`gpt-image-2-2026-04-21` snapshot preserve valid explicit
`WIDTHxHEIGHT` sizes instead of snapping them to presets. Both
dimensions must be multiples of 16, neither may exceed 3840 pixels,
the aspect ratio cannot exceed 3:1, and the image must contain
between 655,360 and 8,294,400 pixels. For example, `1024x640` is
valid. When only `aspectRatio` is specified, Apus still selects
the closest supported size.

OpenAI-specific options live under the `openai` object:

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

`openai.background` accepts `transparent`, `opaque`, or `auto`.
Transparent outputs require `outputFormat` `png` or `webp` and a
transparency-capable OpenAI image model. Apus routes default
`gpt-image-2` transparent-background requests to `gpt-image-1.5`.
`openai.outputCompression` applies to JPEG/WebP outputs and is ignored
for PNG outputs.

The top-level `background` hint is provider-neutral and maps
to the same OpenAI `background` request field when the OpenAI provider
is selected. Providers that do not declare background support return
it in `ignoredOverrides` instead of receiving the unsupported parameter.

To route OpenAI image generation through an Azure OpenAI deployment
instead of `api.openai.com`, see
[Azure OpenAI endpoints](/providers/openai/azure#azure-openai-endpoints).

Microsoft Foundry image generation uses deployed MAI image deployment names
under the `microsoft-foundry/` provider prefix. There is no provider-level
default model because the MAI API expects your deployment name in the
`model` field:

```json5
{
  agents: {
    defaults: {
      mediaModels: {
        image: {
          primary: "microsoft-foundry/<deployment-name>",
          timeoutMs: 600000,
        },
      },
    },
  },
}
```

The provider uses 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

Prompt-only generation can use a custom deployment name with just the
Foundry endpoint configured. Edits with custom deployment names need
onboarding/model metadata so Apus can verify that the deployment is
backed by `MAI-Image-2.5-Flash` or `MAI-Image-2.5`.

Current MAI image models are `MAI-Image-2.5-Flash`, `MAI-Image-2.5`,
`MAI-Image-2e`, and `MAI-Image-2`. See
[Microsoft Foundry plugin](/plugins/reference/microsoft-foundry) for setup
and chat-model behavior.

OpenRouter image generation uses the same `OPENROUTER_API_KEY` and
routes canonical requests through OpenRouter's dedicated `/api/v1/images`
endpoint. Configured custom OpenRouter base URLs retain the existing
chat-completions image route for proxy compatibility. Select OpenRouter
image models with the `openrouter/` prefix:

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

Apus forwards `prompt`, `count`, reference images, and
Gemini-compatible `aspectRatio` / `resolution` hints to OpenRouter.
Current built-in OpenRouter image model shortcuts include
`google/gemini-3.1-flash-image`,
`google/gemini-3-pro-image`, and `openai/gpt-5.4-image-2`. Use
`action: "list"` to see what your configured plugin exposes.

Krea 2 models on fal use fal's native Krea schema instead of the generic
`image_size` schema used by Flux. Apus sends:

- `aspect_ratio` for aspect-ratio hints
- `creativity`, defaulting to `medium`
- `image_style_references` when `image` or `images` are supplied

Select Krea 2 Medium for faster expressive illustration and Krea 2 Large
for slower, more detailed photoreal and textured looks:

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

Krea 2 returns one image per request. Prefer `aspectRatio` for
Krea. Apus maps `size` to the closest supported Krea aspect ratio and
rejects `resolution` for Krea rather than dropping it. Use `fal.creativity`
when you want a native Krea creativity level:

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

MiniMax image generation is available through both bundled MiniMax
auth paths:

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

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: up to 4
- References: one `image` or up to 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: returned as Apus-managed image attachments

Apus intentionally does not expose xAI-native `quality`, `mask`,
`user`, or the `auto` aspect ratio until those controls exist in the shared
cross-provider `image_generate` contract.