Images

Generate images from a text prompt. The route follows the OpenAI Images API, so client.images.generate works unchanged with the base URL https://demo-api.routerplus.com/v1. https://demo-api.routerplus.com/images/generations is an alias for SDKs that omit the /v1 prefix.

To try it without code, pick an image model in the playground.

• The route returns one JSON response by default. Existing clients need no change.
• On the development API, stream: true is optional. It returns keep-alives and then one final image event. See Final-image streaming.
• Images always come back as base64, with no partial previews.
• OpenAI serves the GPT Image models directly. Replicate, Krea and Recraft serve the other models. See Krea image models, Models served by Replicate and Recraft models.

Examples

Each example generates one image and decodes it to out.png.

curl -s https://dev2-api.routerplus.com/v1/images/generations \
  -H "Authorization: Bearer $TM_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"gpt-image-1","prompt":"a red bicycle on a white background","size":"1024x1024","quality":"medium"}' \
  | jq -r '.data[0].b64_json' | base64 -d > out.png

import base64
import os
from openai import OpenAI

client = OpenAI(base_url="https://demo-api.routerplus.com/v1", api_key=os.environ["TM_API_KEY"])

r = client.images.generate(
    model="gpt-image-1",
    prompt="a red bicycle on a white background",
    size="1024x1024",
    quality="medium",
)
with open("out.png", "wb") as f:
    f.write(base64.b64decode(r.data[0].b64_json))
print(r.usage.model_dump()["cost"])  # the exact ledger debit, in USD

import { writeFileSync } from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://demo-api.routerplus.com/v1", apiKey: process.env.TM_API_KEY });

const r = await client.images.generate({
  model: "gpt-image-1",
  prompt: "a red bicycle on a white background",
  size: "1024x1024",
  quality: "medium",
});

const b64 = r.data?.[0]?.b64_json ?? "";
writeFileSync("out.png", Buffer.from(b64, "base64"));
console.log(r.usage); // input/output tokens and cost (USD)

Send your key as Authorization: Bearer tm_vk_... or as x-api-key: tm_vk_.... A missing or invalid key returns 401 with error_type: "auth". You can send HTTP-Referer and X-Title to identify your app. They carry attribution only, no content.

Request

The body is JSON, at most 10 MB. A larger body is a 413 request_too_large. RouterPlus checks every rule below before it reserves money or dispatches. A refused request has no ledger row, no x-tm-attempts header and no charge.

Each model publishes its accepted values for size, quality, background, moderation, output_format and output_compression in /api/models.json under supported_parameters.

• A value outside the declared set of a model is a 400. The message starts with the field name and lists what that model accepts.
• A parameter from this list that a model does not declare is dropped and recorded, like any unknown key.
• An explicit null means "not provided" for every optional parameter above. The OpenAI SDKs send an unset optional as null, so client.images.generate(model=…, prompt=…, n=None, size=None) works. RouterPlus never forwards a null and never records it as a drop.
• model and prompt are required, so null there is a 400.

Everything else

RouterPlus validates and forwards the fields that the selected model declares in supported_parameters. This includes the native Krea reference and editing parameters.

RouterPlus drops and records undeclared keys, and never forwards them. The dropped names are:

• comma-joined in the x-tm-dropped-params response header,
• stored on the ledger row of the attempt,
• visible at GET /v1/generation?id=.

To get a 400 instead of a drop, send "provider": {"require_parameters": true}. The 400 comes before RouterPlus reserves money.

Always base64

RouterPlus always returns the image bytes inline as b64_json. There is no hosted URL: storing images would put your content on RouterPlus disks, which the data policy forbids. response_format: "url" is a typed 400. Decode the base64 yourself, as the examples do.

Response

Without stream: true, the answer is HTTP 200, application/json. The body is OpenAI's ImagesResponse, relayed unchanged except for one added field, usage.cost:

{
  "created": 1790000000,
  "data": [{ "b64_json": "iVBORw0KGgoAAAANSUhEUg..." }],
  "background": "opaque",
  "output_format": "png",
  "quality": "medium",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 12,
    "input_tokens_details": { "text_tokens": 12, "image_tokens": 0 },
    "output_tokens": 1056,
    "total_tokens": 1068,
    "cost": 0.0423
  }
}

RouterPlus never adds the chat field prompt_tokens_details to an images response.

Long-running JSON requests

Image generation can take several minutes. You do not need to change the request or the SDK. An ordinary request keeps its final HTTP status, complete JSON body, headers and billing. Every image count the model supports still works.

While the image is pending, the edge relay keeps its origin connection active, then returns the original result. This avoids Cloudflare's default 125-second proxy read timeout. The relay stores no image content and starts no second generation.

The generation budget is 450 seconds. Set the overall timeout of your client to at least that. Do not retry a lost response automatically: the provider may already have accepted the render.

Final-image streaming

Send "stream": true with "n": 1 for a render that may take several minutes.

1. 01
   After validation, the response starts as HTTP 200 with Content-Type: text/event-stream.
2. 02
   RouterPlus sends a comment at once, then a keep-alive comment every 15 seconds while the image is pending. Comments keep the connection active. They are not partial images or progress estimates.
3. 03
   The final event follows the OpenAI image completion event.
4. 04
   The connection closes.

: rendering

event: image_generation.completed
data: {"type":"image_generation.completed","created_at":1790000000,"b64_json":"iVBORw0KGgoAAAANSUhEUg...","usage":{"cost":0.04},"request_id":"gen_example","response_headers":{"x-tm-provider":"krea","x-tm-attempts":"1"}}

There is one completed event, with no partial-image events and no [DONE] event. The x-request-id HTTP header identifies the request from the start.

An error found before the stream starts keeps its normal HTTP status and JSON body. After the stream starts, a failed request ends with an error event in place of the completion:

event: error
data: {"type":"error","error":{"code":"upstream_error","message":"Image generation failed.","type":"api_error","metadata":{"error_type":"upstream_error"}},"request_id":"gen_example","status":502,"response_headers":{"x-tm-error-code":"upstream_error"}}

• status is the HTTP-equivalent status of the failure. The open SSE response stays HTTP 200.
• error and response_headers carry the error details and the final routing headers.
• The OpenAI SDK raises streaming errors.
• Do not resubmit a disconnected stream or a timed-out request automatically. The provider may already have accepted the render. Use the request ID to read generation usage.

SSE is optional on the development API. Plain JSON uses the edge relay in Long-running JSON requests. Neither SSE nor plain JSON extends the generation budget or guarantees that a provider finishes in time.

These examples keep a slow Qwen render connected and print its final event. The Python example turns automatic retries off, so a lost response does not submit another render.

curl -N --max-time 480 https://dev2-api.routerplus.com/v1/images/generations \
  -H "Authorization: Bearer $TM_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"krea/alibaba/qwen-image-3","prompt":"a red bicycle on a white background","width":1024,"height":1024,"n":1,"stream":true,"partial_images":0}'

import base64
import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    base_url="https://demo-api.routerplus.com/v1",
    api_key=os.environ["TM_API_KEY"],
    timeout=480.0,
    max_retries=0,
)

stream = client.images.generate(
    model="krea/alibaba/qwen-image-3",
    prompt="a red bicycle on a white background",
    n=1,
    stream=True,
    partial_images=0,
    extra_body={"width": 1024, "height": 1024},
)
for event in stream:
    if event.type == "image_generation.completed":
        Path("out.image").write_bytes(base64.b64decode(event.b64_json))
        usage = event.usage.model_dump() if event.usage is not None else {}
        print(usage.get("cost"))

The file holds the provider's image bytes. Use event.output_format for the file extension when it is present. Otherwise inspect the file type.

Billing

Images use the same two SKUs and the same integer micro-USD math as chat (Pricing & billing). Text input bills at prompt, and image output bills at completion.

• Reserve, before RouterPlus contacts a provider: prompt bytes ÷ 4 at the prompt rate, plus n × the per-image ceiling of the model at the completion rate, rounded up. The chat max_tokens default plays no part.
• Settle on the counts the provider reported, rounded down. RouterPlus releases the hold in full.

Example on gpt-image-1 (ceiling 6240 tokens, $5 / $40 per million):

A failed generation costs nothing. A failed attempt, a response over the 32 MiB cap and a 200 with no decodable image all settle at zero. After RouterPlus receives a 200, it never dispatches again, so one request never pays for two renders.

A cancelled render is billed at what the provider reported. If you close the connection mid-render, RouterPlus does not abort the upstream call. The render finishes, RouterPlus reads the usage, and the attempt settles at the provider's numbers. It is never the reservation and never $0. RouterPlus writes nothing to your closed socket.

Krea image models

Krea models have provider-qualified IDs such as krea/krea-3 and krea/google/nano-banana-2.1. /api/models.json lists the current models with the supported_parameters, required_parameters and request_defaults of each. Structured parameters carry their JSON schema under schema.

Each request renders one image (n: 1). RouterPlus runs Krea's asynchronous submit, poll and download flow. Your request returns the completed OpenAI-style base64 image.

{
  "model": "krea/krea-3",
  "prompt": "Change the mug to blue, keeping everything else the same.",
  "image_urls": ["data:image/png;base64,..."],
  "resolution": "2k",
  "thinking_mode": "fast",
  "regional_edit": true
}

Krea 3 parameters:

• image_urls: up to eight.
• negative_prompt: optional, up to 1,024 characters.
• seed.
• style_urls (style references): not in Krea's API yet. The field is a 400 before dispatch.
• Regional edits are experimental.
• thinking_mode: fast or high. ultra requires resolution: "2k" and cannot be combined with regional editing.
• Custom canvas: send both width and height (positive integers up to 4096), and omit resolution and aspect_ratio. Krea rounds the request to a supported canvas, so exact pixel dimensions are not guaranteed.
• Otherwise the default is 2K with automatic framing. The model lists its optional aspect_ratio values.

A Krea 3 reference is a Krea asset URL or an inline PNG, JPEG or WebP data URI. RouterPlus uploads inline images to Krea's assets endpoint before it submits the job. The playground also accepts local files. References count toward the 10 MB request limit. Other Krea models accept the external reference URLs their schemas declare.

Pricing:

• Krea 3 is free during early access.
• Other enabled Krea models charge the fixed USD price for the selected settings and references, shown on their model pages.
• RouterPlus holds the published maximum of the model, then settles the selected price only after a successful render. It does not convert Krea's in-app compute units into API dollars.
• A model without verified price rules is unavailable until those rules exist.

Qwen Image 3 (krea/alibaba/qwen-image-3) and Seedream 5 Pro (krea/bytedance/seedream-5-pro) price the requested total pixels, width × height:

• A Qwen 2048×512 image costs $0.04, the same as 1024×1024.
• A Seedream 3072×768 image costs $0.045 before additional references.
• Crossing the area threshold raises the base price, even when only one dimension changes.
• Qwen defaults to 1024×1024. Seedream defaults to 1536×1536. For another size, send positive whole-pixel width and height. The parameter schema of each model has its dimension bounds.
• The reservation ceilings are $0.075 (Qwen) and $0.117 (Seedream).

Models served by Replicate

Replicate serves Nano Banana Pro, FLUX.2 [max] and [pro], Seedream 5.0 Lite, Grok Imagine Image and Wan 2.7 Image Pro. RouterPlus bills them at Replicate's published price for the render, with no margin (Pricing & billing). The reservation is n × the per-image ceiling of the model (Per image ≤). The charge is the listed price. These models take aspect_ratio (or size) and resolution in place of quality.

• Replicate counts FLUX.2 output megapixels in whole megapixels, rounded up. A 0.5MP render bills as 1.
• Prices were read from Replicate on 2026-10-12.
• Wan 2.7 Image Pro answers in PNG only, so one answer holds at most 8,388,608 pixels. n can be up to 4 at the 1K sizes, 3 at 2048x1152 and 1152x2048, and 2 at 2048x1536, 1536x2048, 2048x2048 and auto. A larger n is a 400 before anything renders, so it costs nothing.

Recraft models

Recraft serves its models directly, with IDs of the form recraft/<model>, such as recraft/recraftv4_1 or recraft/recraftv2_vector. RouterPlus bills them at Recraft's published price, passed through. The charge is the cost Recraft reports for the request.

Prices are per image. A request with style_reference_urls adds $0.005 once, because Recraft creates a style from the references. The per-image ceiling includes that fee. Prices were read from Recraft on 2026-10-16.

• Output:
  • _vector models return SVG. data[].b64_json holds the SVG text, and output_format is svg.
  • Raster models return WebP by default. Send image_format: "png" for PNG.
• Images per request: n takes 1 to 6.
• size: every model accepts the 14 aspect ratios (1:1, 16:9, 6:10, …). Raster models also accept their exact WxH sizes. Pro models use the 2K ones. Omit size to let Recraft choose from the prompt.
• Styles:
  • Every model except V4.1 Flash takes style_id (a Recraft style) or style_reference_urls: one to ten PNG, JPEG or WebP URLs or data URIs. Never both.
  • You can reuse the style_id from the response.
  • V4 Styles models require one of the two.
  • style_match is flexible or precise on V4 and newer, and regular on V2 and V3.
• V2 and V3 only: style (a curated style name such as Photorealism) and negative_prompt. Prompts on V2 and V3 are limited to 1,000 characters. On newer models the limit is 10,000.
• V3 only: text_layout. controls takes colors and background_color on every model, plus artistic_level and no_text on V3.
• Seed: RouterPlus passes seed to Recraft as its random_seed.

{
  "model": "recraft/recraftv4_styles_vector",
  "prompt": "a lighthouse on a cliff",
  "size": "16:9",
  "style_reference_urls": ["https://example.com/brand-reference.png"]
}

Errors

• Error bodies use the OpenAI error envelope, with the canonical class in error.metadata.error_type. Every failure also has the class in x-tm-error-code.
• RouterPlus never relays a provider's own error body. The provider's status is in x-tm-upstream-status.
• After SSE begins, the terminal error event carries these details, and the HTTP status can no longer change. See Final-image streaming.
• An image model sent to POST /v1/chat/completions, POST /v1/messages or POST /v1/decisions is a 400 invalid_request that names /v1/images/generations.

Errors lists every error class and its fix.

Limits

Response headers

There is no image-specific header. Browsers can read all of these except x-tm-error-code and x-tm-route-plan-id, which are not CORS-exposed. For SSE, the response_headers extension of the completed event also carries the final routing headers.

Request data

Prompts, image bytes and any revised_prompt follow the Data policy. Process logs, telemetry and the billing ledger contain metadata only. Telemetry records the response byte size, to measure throughput.

Model discovery

curl -s "https://demo-api.routerplus.com/v1/models?output_modalities=image" \
  -H "Authorization: Bearer $TM_API_KEY"

Every row of GET /v1/models carries architecture.output_modalities, for example ["image"]. The public feed https://demo.routerplus.com/api/models.json carries, for image models:

• output_modalities
• the full supported_parameters descriptor map
• max_output_tokens, the per-image ceiling

See GET /v1/models and Models & catalog.

BYOK

Image generation works through an openai provider connection.

• List on the connection the exact image ids you intend to send. Matching is literal. An id the connection does not carry is a 404 model_unavailable.
• The model's metadata (ceiling, descriptors) still comes from the RouterPlus catalog.
• usage.cost is 0 and RouterPlus charges nothing. OpenAI bills your own account for the render.

See Bring your own key.

See also: Models & catalog · Pricing & billing · Errors · Wire compatibility