Image generation

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.

Using it

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

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