# Images

> Generate images with the image models of your providers, from the SDK or from a chat.

The `generate_image` tool makes images from a text prompt and saves them as files in the workspace. It can also edit an image, or match the style of one, when you give it reference images. The tool uses the image models of every connected provider that has an image endpoint.

| Provider | Image models | Credentials |
| - | - | - |
| `openrouter()` | About 60, from pi-ai's catalog: GPT Image, Gemini image, FLUX, Seedream, Recraft, Grok Imagine and others | OpenRouter API key |
| `openai()` | `gpt-image-2`, `gpt-image-1`, `gpt-image-1-mini` | Platform API key (`sk-…`). A ChatGPT sign-in does not cover the Images API. |
| `google()` | `gemini-3.1-flash-image`, `gemini-3-pro-image`, `gemini-3.1-flash-lite-image`, `gemini-2.5-flash-image` | Gemini API key (`GEMINI_API_KEY`) |
| `xai()` | `grok-imagine-image-2.0`, `grok-imagine-image-quality` | xAI API key or SuperGrok sign-in |

## What a call does

1. The model calls `generate_image` with a `prompt` and, optionally, a `model`, a `path`, an `aspect_ratio`, a count `n` (1 to 4), `references` and `transparent`.
2. The tool sends one request to the provider. Gemini and OpenRouter return one image per request, so the tool sends `n` requests in parallel for them.
3. The tool saves each image at full size. The extension follows the format the provider returns. Several images get `-1`, `-2` suffixes. Without a `path`, the files go to `generated-images/`.
4. Next to each image, the tool writes a `.json` record with the prompt, the provider, the model, the aspect ratio, the references, the cost and the date. The record keeps the origin of each asset with the file.
5. The tool returns the saved paths, the size of each image, the cost when the provider reports it, and a preview of each image. The preview is at most 768 px on its longest edge. To look at the full image, the model reads the file with `read_file`.

The tool refuses a `path` or a reference outside the working directory. It refuses `references` for a model that does not take them, and `transparent` for a model that cannot make a transparent background. Each error names the models that can.

## Pick a model

The tool description lists up to 15 models, the default first. Each line is `<provider>/<model id>`, with `[ref]` for a model that takes reference images and `[alpha]` for a model that can make a transparent background. To see every model, the model calls `generate_image` with `list: true`.

The `model` argument takes `<provider>/<model id>`, for example `openrouter/google/gemini-3-pro-image`. A bare model id also works when only one provider serves it.

## Use it from the SDK

Without `sources`, the tool uses the image endpoints of the run's providers (`AgentOptions.provider`, the primary and its fallbacks):

```ts
import { createAgent, createGenerateImageTool } from 'zidane'
import { anthropic, openrouter } from 'zidane/providers'
import { basicTools } from 'zidane/presets'

const agent = createAgent({
  provider: [anthropic(), openrouter()],
  tools: { ...basicTools, generate_image: createGenerateImageTool() },
})
await agent.run({ prompt: 'Make a 16:9 snowy pine forest texture at assets/snow.png.' })
```

To use a provider that does not run the chat, pass it in `sources`. To set the default model, pass `defaultModel`:

```ts
const images = openrouter().images!
createGenerateImageTool({
  sources: [{ provider: 'openrouter', images }],
  defaultModel: 'openrouter/black-forest-labs/flux.2-pro',
})
```

A provider with an image endpoint has `provider.images`, a `ProviderImages`. Call `images.generate({ model, prompt, aspectRatio, count, references, transparent }, signal)` to get base64 images without the tool.

## Use it in the apps

The terminal and desktop apps give every Build and Codemode session `generate_image` when a connected provider can generate images. The tool goes through [approvals](https://zidane.si/docs/approvals.md) like any tool that writes files.

| Setting | Does |
| - | - |
| Image generation | Gives the agent `generate_image`. On by default. |
| Image model | The default model, as `providerKey/modelId`. Empty: the first available provider's default. A model that is no longer available falls back the same way. |

In the desktop app, open the model picker and select the Image tab to choose the default image model. The tab lists the image models of your providers. An images icon marks a model that takes reference images, and a checkerboard icon marks a model that can make a transparent background. Hover an icon for what it means. A provider that cannot generate with its current credentials shows its models greyed out, with a lock icon that gives the reason. The tab has the same search field, Legacy switch and provider pills as the Chat tab, and both tabs keep one height.

While a call runs, the transcript shows one frame per requested image, at the requested aspect ratio. When the images arrive, each one decodes, then fades in, and the frame keeps its size. Click an image to open it full size. Click the path under it to open the file. Each saved image is also listed in the Artifacts panel.

## Costs

Each call bills the provider. OpenRouter reports the cost of each request, and the tool shows it and writes it in the record. The other providers do not report a cost in the response, so the tool shows none. The tool description tells the model to generate one image, look at it, and then change the prompt, instead of generating many at once.

## Reference

- [`zidane/tools`](https://zidane.si/docs/reference/tools.md)
- [`zidane/providers`](https://zidane.si/docs/reference/providers.md)