Image generation
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.
Draw a picture
$STREAM_ACCELERATION_URL is your router's URL and $SERVER_TOKEN is a server token. Image generation is server-side only.
Not in the Node.js SDK yet. Showing cURL.
Not in the Python SDK yet. Showing cURL.
Not in the Ruby SDK yet. Showing cURL.
Not in the PHP SDK yet. Showing cURL.
Not in the .NET SDK yet. Showing cURL.
Not in the Rust SDK yet. Showing cURL.
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 -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"}}'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/models. 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
{
"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:
Not in the Python SDK yet. Showing cURL.
Not in the Ruby SDK yet. Showing cURL.
Not in the PHP SDK yet. Showing cURL.
Not in the .NET SDK yet. Showing cURL.
Not in the Rust SDK yet. Showing cURL.
import { Client } from "@stream-io/stream-agents";
const api = new Client();
const [fastest] = await api.router().routes("image");api, err := client.New(stream.Backend{})
if err != nil {
return err
}
routes, err := api.Routes(ctx, acceleration.ModalityImage)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-fastthat 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 withtimeout. 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_microsis what the request cost. The money is held before the job starts, so a spend limit 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:
name: support
mode: text
llm: llm-fast
image: image-fastimage 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
imagetarget. 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/generationsis, when it is drawn, under the session's attribution. App, user, team and session 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_msdoesn't limit it. The draw gets 240 seconds. - It replaces a tool of your own. If you registered your own
generate_imagetool to draw pictures, a config withimageset uses the built-in one in its place. Withoutimage, your tool runs as before.