# Image generation

> **Note:** This page covers every SDK. Each sample is labelled with its language and where it runs: the client (your app, signed in as the user) or the server (with your API secret).

The image router draws pictures from a prompt. Call it from your server with `POST /v1/image/generations`, or let an agent draw them in a conversation with the built-in [`generate_image` tool](#from-an-agent).

## Draw a picture

`$STREAM_ACCELERATION_URL` is your router's URL and `$SERVER_TOKEN` is a [server token](https://getstream.io/agents/docs/auth/). Image generation is server-side only.

**Go (server)**

```go label="Go"
api, err := stream.NewClient(stream.Backend{})
if err != nil {
	return err
}

target, shape := "image-fast", "16:9"
drawn, err := api.Router("").Image().Generate(ctx,
	"A yellow watering can beside a seedling, flat illustration, no text",
	&acceleration.ImageOptions{Target: &target, AspectRatio: &shape},
)
if err != nil {
	return err // a generation that drew nothing comes back with its ErrorCode set, and an error
}
// Data holds the picture's bytes, already decoded from base64.
err = os.WriteFile("watering-can.png", drawn.Images[0].Data, 0o644)
```

**cURL**

```bash label="cURL"
curl -X POST "$STREAM_ACCELERATION_URL/v1/image/generations" \
  -H "api_key: $STREAM_API_KEY" -H "stream-auth-type: jwt" \
  -H "Authorization: Bearer $SERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A yellow watering can beside a seedling, flat illustration, no text", "options": {"target": "image-fast", "aspect_ratio": "16:9"}}'
```

>
> **Info:** The Go SDK draws with `Router(...).Image().Generate`. From the other SDKs, send the request to `POST /v1/image/generations`, as in the cURL sample.
>

The request takes a `prompt`, `options` and optional `tags`, the cost labels the request is counted under.

| Option                                     | What it does                                                                                      |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| `target`                                   | A route or a `provider/model`. Defaults to `image-fast`.                                          |
| `providers`                                | A priority list of routes, providers or `provider/model`s. It wins over `target`.                 |
| `n`                                        | How many pictures, 1 to 4.                                                                        |
| `size`                                     | Width by height, such as `1024x1024`, on a model that takes a size. FAL draws 512 to 2048 a side. |
| `aspect_ratio`                             | The shape, such as `16:9`, on a model that takes a shape.                                         |
| `seed`, `negative_prompt`, `output_format` | On a model that takes them.                                                                       |

An option only goes to the models that take it, so it is either honoured or the request is refused. It is never dropped.

## The response

```json
{
  "id": "img_1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
  "status": "completed",
  "provider": "fal",
  "model": "alibaba/qwen-image-3/text-to-image",
  "cost_micros": 0,
  "images": [
    {
      "data": "iVBORw0KGgoAAAANSUhEUgAA...",
      "media_type": "image/png",
      "width": 1024,
      "height": 576
    }
  ]
}
```

| Field                 | What it is                                                                                                                                                                |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                  | The generation's id, for your logs. Nothing is stored under it.                                                                                                           |
| `status`              | `completed` or `failed`.                                                                                                                                                  |
| `images`              | The pictures, base64. Each has `media_type` (`image/png` or `image/jpeg`), `width`, `height`, and `seed` when the provider reports one. Empty when the generation failed. |
| `provider`, `model`   | Who drew it and with which model. `provider` is absent when nothing reached a provider.                                                                                   |
| `cost_micros`         | What the request cost, in millionths of a dollar. Zero when it failed.                                                                                                    |
| `error_code`, `error` | Why nothing was drawn, on a failed generation.                                                                                                                            |

The `cost_micros` in the sample stands in for the real figure. The pictures come back in the response, never as a link, and the router keeps no copy. Save what you want to keep.

A generation that reached a provider is a `200` whether it drew anything or not. A failed one has `status: "failed"` and costs nothing:

| `error_code`         | Why                                                               |
| -------------------- | ----------------------------------------------------------------- |
| `content_filtered`   | A safety filter refused the prompt or the picture.                |
| `unsupported_option` | No model on the route could honour a size, shape or other option. |
| `provider_failed`    | The provider failed in some other way.                            |
| `timeout`            | The 240 seconds ran out.                                          |
| `cancelled`          | The caller hung up.                                               |

A request that can't be routed at all, such as one naming a route that doesn't exist, is a `400`.

## Routes

| Route           | Model                  | What it is for                                                                    |
| --------------- | ---------------------- | --------------------------------------------------------------------------------- |
| `image-fast`    | Qwen Image 3 on FAL    | The default. Takes a size, a shape, a seed and a negative prompt.                 |
| `image-quality` | Gemini 3.1 Flash Image | Follows a long prompt and writes legible text in the picture. Takes a shape only. |

The four shared routes, such as `en-low-latency`, work here too. List the image routes, default first, with the models each one resolves to now:

**Node.js (server)**

```ts label="Node.js"
import { Client } from "@stream-io/stream-agents";

const api = new Client();
const [fastest] = await api.router().routes("image");
```

**Go (server)**

```go label="Go"
api, err := client.New(stream.Backend{})
if err != nil {
	return err
}
routes, err := api.Routes(ctx, acceleration.ModalityImage)
```

**cURL**

```bash label="cURL"
curl "$STREAM_ACCELERATION_URL/v1/image/routes" \
  -H "api_key: $STREAM_API_KEY" -H "stream-auth-type: jwt" \
  -H "Authorization: Bearer $SERVER_TOKEN"
```

## Time, limits and billing

- **Time.** The response comes back once the pictures are drawn. On `image-fast` that is usually a minute or two: calls of 60 to 130 seconds have been observed. A request gets at most 240 seconds, after which it fails with `timeout`. Set your HTTP client's timeout above that. A caller that hangs up cancels the job at the provider.
- **Limits.** At most 4 pictures a request. Each picture is at most 10 MiB and 4096 pixels a side.
- **Billing.** Each picture is billed at the model's price, and `cost_micros` is what the request cost. The money is held before the job starts, so a [spend limit](https://getstream.io/agents/docs/spend-limits/) that covers the caller refuses a picture it can't pay for. A failed generation costs nothing.

## From an agent

Name an image route as `image` in the agent's config, and a text agent is offered a built-in tool, `generate_image`, to draw pictures in the conversation:

```yaml title="agents/support/agent.yaml"
name: support
mode: text
llm: llm-fast
image: image-fast
```

`image` takes a route or a `provider/model`, like `llm`. A target the deployment can't draw with is refused when the config is saved, and an empty `image` turns the tool off again.

The tool takes a `prompt` and an optional `aspect_ratio`: `1:1`, `4:3`, `3:4`, `16:9` or `9:16`. Left out, the picture is square.

How it behaves:

- **It answers at once.** The tool tells the model the picture is on its way, and the turn ends. The picture is drawn in the background and posted into the conversation as a message from the agent, with the picture attached, usually a minute or two later.
- **A failure is posted too.** When a picture can't be drawn, the agent posts a short message saying why, such as the safety filter or a spending limit, instead of nothing.
- **Off by default.** An agent draws only when its config names an `image` target. There is no default target, and a session can't turn it on.
- **Text agents in Stream Chat only.** The tool is offered in written conversations that have a Stream Chat channel. A voice session, or a session without a channel, such as an incognito one, isn't offered it.
- **At most 4 pictures a reply.** A fifth call in the same reply draws nothing, and the model is told so.
- **Billing.** Each picture is billed as `POST /v1/image/generations` is, when it is drawn, under the session's attribution. App, user, team and session [spend limits](https://getstream.io/agents/docs/spend-limits/) all apply.
- **Not bound by the tool timeout.** The picture is drawn after the tool has answered, so the session's [`tool_timeout_ms`](https://getstream.io/agents/docs/tool-calling-and-dispatch/#timeouts) doesn't limit it. The draw gets 240 seconds.
- **It replaces a tool of your own.** If you registered your own `generate_image` tool to draw pictures, a config with `image` set uses the built-in one in its place. Without `image`, your tool runs as before.

---

For the most recent version of this documentation, visit [https://getstream.io/agents/docs/image-generation/](https://getstream.io/agents/docs/image-generation/).