Use rb.image() to generate images. It supports both one-shot generation and streaming, and automatically handles async task polling when needed.
One-shot generation
import { RouterBrain } from '@router-brain/sdk';
const rb = new RouterBrain('sk-your-api-key');
// URL output (default)
const result = await rb.image({
model: 'dall-e-3',
prompt: 'An orange cat sleeping under cherry blossoms, sunset, warm tones',
size: '1024x1024',
}).json();
console.log(result.created); // timestamp
console.log(result.data[0].url); // image URL
console.log(result.usage?.images); // number of images generated
// Base64 output
const result2 = await rb.image({
model: 'dall-e-3',
prompt: 'Landscape painting, ink wash style',
size: '1792x1024',
response_format: 'b64_json',
}).json();
console.log(result2.data[0].b64_json); // base64 string
Streaming (SSE)
For streaming models, use .stream() to receive data as it arrives:
const stream = await rb.image({
model: 'stabilityai/stable-diffusion-3',
prompt: 'Cyberpunk city at night',
stream: true,
}).stream();
for await (const chunk of stream!) {
const text = new TextDecoder().decode(chunk);
console.log(text);
}
SSE events you'll receive:
| Event | Meaning |
|---|---|
success | An image was generated, carries URL or base64 data |
error | An image failed, carries error details |
complete | All images are done, carries final usage count |
Async task polling
Some models process asynchronously and return a task_id. Use .task() to poll until it's complete:
const result = await rb.image({
model: 'stabilityai/stable-diffusion-3',
prompt: 'A unicorn under the stars',
}).task({
pollInterval: 2000, // check every 2 seconds
});
console.log(result.task_status); // 'success'
console.log(result.data[0].url); // generated image URL
console.log(result.usage.images); // usage
To cancel polling after a timeout:
const controller = new AbortController();
setTimeout(() => controller.abort(), 30000); // 30s timeout
try {
const result = await rb.image({
model: 'stabilityai/stable-diffusion-3',
prompt: '...',
}).task({ signal: controller.signal });
} catch (err) {
console.error('Task aborted or failed:', (err as Error).message);
}
Available methods
| Method | Returns | When to use |
|---|---|---|
json() | Promise<ImageResponseJson> | Standard generation — get results as JSON |
stream() | Promise<ReadableStream<Uint8Array> | null> | Real-time streaming generation |
task(opts?) | Promise<ImageTaskResponseJson> | Async models — poll until complete |
httpStatus() | Promise<number> | Check HTTP status before calling .json() |
Request parameters
| Parameter | Type | Required | What it does |
|---|---|---|---|
model | string | Yes | The model to use, e.g. 'dall-e-3' |
prompt | string | Yes | Your image description |
image | ImageAdapterImage | ImageAdapterImage[] | No | Reference image(s) for image-to-image |
size | string | No | Image dimensions, e.g. '1024x1024' |
stream | boolean | No | Stream generation as it happens |
response_format | 'url' | 'b64_json' | No | Output format, default 'url' |
upstream_options | Record<string, any> | No | Model-specific options |
headers | Record<string, string | string[]> | No | Custom HTTP headers |
See Image generation docs for provider details and full reference.