# Image generation

Let the agent generate images from a text prompt via OpenAI's Images API.

## Overview

`image_generation` exposes a function that takes a prompt and returns one or more PNG / JPG / WebP files. Each generated image is **persisted to your account's `generated_files` table** and served back through a signed URL — so the LLM (and the user's chat panel) can reference the image without us re-uploading bytes everywhere.

Use it when:

- The agent needs to produce an illustration, diagram sketch, or hero image inline.
- A workflow turns a structured spec into a visual (e.g. *"marketing email with header image of X"*).
- A user asks the agent to mock something up.

Skip it for: production-grade design assets (use a dedicated tool), edits of an existing image (currently unsupported in this tool — use the OpenAI Edit endpoint via a `function` tool).

## Configuration

| Field | Values | Notes |
| --- | --- | --- |
| Model | `gpt-image-1`, `gpt-image-2`, `dall-e-3` | Newer models accept `quality` and `background`; `dall-e-3` does not (we drop them automatically). |
| Size | `1024x1024`, `1024x1792`, `1792x1024` | Square, portrait, landscape. Invalid sizes are coerced to `1024x1024`. |
| Quality | `low`, `standard`, `high` | Higher = sharper detail and more tokens. |
| Format | `png`, `jpg`, `webp` | Storage format. PNG preserves transparency. |
| Background | `auto`, `transparent`, `opaque` | Only honored by `gpt-image-*` models. |

The model may also pass `size` and `quality` on each call to override the defaults (e.g. *"make this portrait, high quality"*).

## Example

User turn: *"Generate a flat-style illustration of a robot reading a book, transparent background."*

The LLM issues:

```json
{
  "prompt": "Flat-style illustration of a robot reading a book, soft pastel colors",
  "size": "1024x1024",
  "quality": "high"
}
```

Backend response fed to the model:

```json
{
  "status": "completed",
  "image_urls": ["https://app.systalink.fr/files/abc123/download?sig=..."],
  "images": [{
    "filename": "agent-image-abc12345.png",
    "url": "https://app.systalink.fr/files/abc123/download?sig=...",
    "preview_url": "https://app.systalink.fr/files/abc123/preview?sig=...",
    "public_id": "abc123...",
    "format": "png"
  }]
}
```

The agent then replies with a sentence and the image renders inline in the chat panel via the preview URL.

## Cost

Image generation is billed by OpenAI per image and depends on **model × size × quality**:

- `gpt-image-1` and `gpt-image-2` charge by tokens (input + output image); `high` quality at 1792×1024 is the most expensive combination.
- `dall-e-3` is flat-priced per image, with `hd` (mapped from our `high`) roughly 2x `standard`.

A single high-quality 1792×1024 `gpt-image-*` call can cost an order of magnitude more than a chat completion — surface this to the user if your workflow auto-generates images.

## Best practices

- **Be specific.** *"Hero image, 16:9, vector style, navy + teal palette, no text"* yields a more predictable result than *"a cool banner"*.
- **Pin the model.** If you settle on `gpt-image-2` standard, set it in the modal so the agent does not silently fall back to a smaller model.
- **Persist the public_id.** Downstream nodes can reference the generated file by its `public_id`, e.g. to attach it to an email.

## Gotchas

- Without an OPENAI_API_KEY configured on the backend, the tool returns `{"status": "error", "message": "OPENAI_API_KEY is not configured."}` and the agent will surface that to the user.
- `gpt-image-1` rejects `response_format`; we strip it automatically. `dall-e-3` rejects `background`; we strip that too. Inspect the execution log if a call comes back empty.
- Maximum `n=4` images per call. Higher values are clamped.

---

*Source: https://agentbuilder.systalink.sn/docs/tool-image-generation — human documentation.*
*Other language: [/docs-md/fr/tool-image-generation.md](/docs-md/fr/tool-image-generation.md).*
*Machine-readable index: [/llms.txt](/llms.txt).*