An agent with the `generate_image` tool can produce an image from a text prompt. The result is saved as a PNG artifact and shows up in chat like any other attachment.

## Setup

Two things are required.

1. **An OpenAI provider.** Image generation runs against OpenAI's Images API, so the instance needs a provider of type `openai` with a working key. Nakama uses your default provider when it is an OpenAI one, otherwise the first OpenAI provider configured. The key comes from that provider, or from `OPENAI_API_KEY`.
2. **A model, set in Settings.** Pick **Image generation model** in the same card group as the vision and transcription models. The only allowlisted choice today is `gpt-image-2`.

Until a model is set, the tool refuses with `Configure an image generation model in Settings before generating images.` The card shows **Not configured** in that state, and **No OpenAI provider** when the provider is the missing half.

Assign the `generate_image` tool to a profile the same way as any other builtin. See [Builtin tools](/builtin-tools).

## Using it

Ask in plain language. The agent calls `generate_image` with a prompt and, optionally, a filename and a size.

| Parameter | Required | Notes |
| --- | --- | --- |
| `prompt` | yes | What to draw |
| `filename` | no | Output name under `artifacts/`, defaults to a generated `.png` |
| `size` | no | `1024x1024` (default), `1024x1536`, `1536x1024`, or `auto` |

The model is deliberately **not** a parameter. It comes from Settings, so a prompt cannot talk the agent into a model the workspace has not allowlisted. An unsupported size is rejected with the allowed list rather than silently rounded to the nearest one.

## Where the image goes

Each generated image is written under the profile workspace:

```
~/.nakama/orgs/{orgId}/profiles/{profileId}/artifacts/
```

alongside a `.nakama-meta.json` sidecar, so it appears in **Files** with the right type and timestamp. When the call happens inside a chat session, the image is also saved as a session attachment, which is what makes it render inline in the conversation rather than only in the Files list. Web chat and the channel bridges both recognize `generate_image` output, so a Telegram or Discord turn gets the picture too.

Attachments are capped at 5 MB.

See [Artifacts and files](/artifacts) for previewing, editing, and publishing what comes out.

## Cost

Every generation records usage through the same token pricing bridge as chat, so image spend shows up next to model spend rather than being invisible. When the API returns a usage breakdown, that is what gets recorded. When it does not, Nakama estimates: input tokens from the prompt length, output tokens from the requested size. Estimated figures are recorded as estimates, not passed off as measured.

## Limits

- One model, `gpt-image-2`, and one provider type, OpenAI. There is no Stability, Replicate, or local diffusion path.
- No image editing or variations. Generation from a prompt only.
- No streaming or progress. A generation is one tool call that returns when the image is ready.