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.

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

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

const api = new Client();
const [fastest] = await api.router().routes("image");
Go
api, err := client.New(stream.Backend{})
if err != nil {
	return err
}
routes, err := api.Routes(ctx, acceleration.ModalityImage)
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 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:

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 all apply.
  • Not bound by the tool timeout. The picture is drawn after the tool has answered, so the session's tool_timeout_ms 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.