POST /v1/images/generations

Generate images from a text prompt. This is the OpenAI Images API surface: point client.images.generate at https://dev-api.routerplus.com/v1 and the call works unchanged. The path https://dev-api.routerplus.com/images/generations is an alias for the same handler, for SDKs that omit the /v1 prefix.

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

By default the route returns one JSON response. Existing clients do not need to enable streaming on the development API. Optional stream: true returns keep-alives followed by one final image event. Images always come back as base64; streaming does not enable partial previews. Models served by Krea also accept reference images and editing controls through this same JSON endpoint; see Krea image models. The GPT Image models are served by OpenAI direct; the others (Nano Banana Pro, FLUX.2 [max] and [pro], Seedream 5.0 Lite, Grok Imagine Image, Wan 2.7 Image Pro) by Replicate, billed at Replicate's published price — see Models served by Replicate.

Authentication

A missing or invalid key returns 401 with error_type: "auth". Optionally send HTTP-Referer and X-Title to identify your app (content-free attribution).

Request

JSON body, capped at 10 MB (413 request_too_large above that). Every rule below is checked before anything is reserved or dispatched, so a refused request has no ledger row, no x-tm-attempts header, and no charge.

The accepted values for size, quality, background, moderation, output_format and output_compression are per model and published in /api/models.json under supported_parameters. A value outside a model's declared set is a 400 whose message starts with the field name and lists what that model accepts. One of these parameters that a model does not declare at all is dropped and recorded, like any unknown key.

An explicit null means "not provided" for every optional parameter above, exactly like omitting the key: the OpenAI SDKs serialise an unset optional as null, so client.images.generate(model=…, prompt=…, n=None, size=None) works. A null is never forwarded upstream and never recorded as a drop. model and prompt are required, so null there is still a 400.

Everything else

Fields declared by the selected model in supported_parameters are validated and forwarded, including native Krea reference and editing parameters. Undeclared keys are dropped and recorded, never forwarded and never guessed at (D8 §2). The dropped names are comma-joined in the x-tm-dropped-params response header, stored on the attempt's ledger row, and visible at GET /v1/generation?id=. To refuse instead of dropping, send "provider": {"require_parameters": true} — a would-be drop then becomes a 400 before any money is reserved. provider itself is consumed by the gateway and never forwarded.

Always base64

The gateway always returns the image bytes inline as b64_json. There is no hosted URL: storing an image would make this service stateful and would put buyer content on our disks, which the data policy forbids. response_format: "url" is therefore a typed 400, not a quietly different answer. Decode the base64 yourself — the examples below do it in three languages.

Response

Without stream: true: HTTP 200, application/json, with OpenAI's own ImagesResponse relayed untouched except for one added field:

{
  "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
  }
}

The chat surface's prompt_tokens_details is never injected here; an images response keeps its own shape.

Long-running JSON requests

Image generation can take several minutes. An ordinary request keeps its final HTTP status, complete JSON body, headers, and billing behavior. No request or SDK changes are required; every image count supported by the selected model is preserved, and errors retain their normal final HTTP status.

The edge relay keeps its origin connection active while the image is pending, then returns the original result. This addresses Cloudflare's default 125-second proxy read timeout without storing image content or initiating another generation.

The gateway's generation budget is 450 seconds. Allow at least that long in your client's overall timeout. Do not automatically retry a lost response: 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. After validation the response starts as HTTP 200 with Content-Type: text/event-stream. A comment is sent immediately, followed by 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. The final event follows the OpenAI image completion event:

: 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"}}

The connection then closes. There is one completed event, no partial-image events, and no additional [DONE] event. b64_json is the final image. created_at is its response timestamp. Output metadata such as size, quality, background, and output_format is included only when it is known from the result; requested values are not presented as measured output. usage retains the same accounting information as the JSON response, including the exact usage.cost where available.

request_id and response_headers are RouterPlus extensions. Since the HTTP headers have already been sent, response_headers carries final routing metadata such as x-tm-provider, x-tm-attempts, and x-tm-upstream-status. The ordinary x-request-id HTTP header identifies the request from the start.

Errors found before the stream starts retain their normal HTTP status and JSON body. After it starts, an unsuccessful request ends with an error event instead of a 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"}}

The status field is the failure's HTTP-equivalent status; the open SSE response itself remains HTTP 200. Error details and final routing headers are carried in error and response_headers. The OpenAI SDK raises streaming errors. Do not automatically resubmit a disconnected stream or a timed-out request: the provider may already have accepted the render. Use the request ID to inspect generation usage.

Choose SSE when you want an explicit event stream. It is optional on the development API: normal JSON uses the edge relay described above. Neither transport extends the generation budget or guarantees that a provider completes in time.

Billing

Same two SKUs as chat, same integer micro-USD math (Pricing & billing): text in bills at prompt, image out bills at completion.

• Reserve, before any provider is contacted: prompt bytes ÷ 4 at the prompt rate, plus n × the model's per-image ceiling at the completion rate, rounded up. The chat path's max_tokens default plays no part here.
• Settle, on the provider-reported counts, rounded down. The hold is released in full.

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

All-or-nothing. A generation either arrives whole or costs nothing. A failed attempt, a response over the 32 MiB cap, and a 200 that carries no decodable image all settle at zero. Once a 200 has been received the gateway never re-dispatches, so one request can never buy two renders.

A cancelled render is billed at what the provider reported. If you hang up mid-render the upstream call is not aborted: the render finishes, the usage is read, and the attempt settles the provider's own numbers — never the reservation, never a pretend $0. Nothing is written to your dead socket.

Krea image models

Krea models have provider-qualified IDs such as krea/krea-3 and krea/google/nano-banana-2.1. Discover the current list and each model's supported_parameters, required_parameters, and request_defaults at /api/models.json. Structured parameters carry their JSON schema under schema. Each request renders one image (n: 1). Krea's asynchronous submit/poll/download flow is handled by the gateway; 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 accepts up to eight image_urls, optional negative_prompt (up to 1,024 characters), and seed. Style references (style_urls) are not yet available in Krea's API; supplying that field returns 400 before dispatch. Regional edits are experimental. Use fast or high thinking; ultra requires resolution: "2k" and cannot be combined with regional editing. For a custom canvas, provide both width and height (positive integers up to 4096), and omit resolution and aspect_ratio. Exact pixel dimensions are not guaranteed: Krea rounds the request to a supported canvas. Otherwise the default is 2K and automatic framing. The optional aspect_ratio values are listed with the model.

For Krea 3 references, supply a Krea asset URL or an inline PNG, JPEG, or WebP data URI. The gateway uploads inline images to Krea's assets endpoint before submitting the job. The playground also accepts local files. References remain subject to the 10 MB request limit. Other Krea models accept the external reference URLs their schemas declare.

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. The gateway holds the model's published maximum, then settles the selected price only after a successful render; it does not interpret Krea's in-app compute units as API dollars. Models without verified price rules are unavailable until those rules are established.

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

For example, Qwen's 2048×512 image costs $0.04, just like 1024×1024. Seedream's 3072×768 image costs $0.045 before additional references. Crossing the area threshold increases the base price even when only one dimension changes. Qwen defaults to 1024×1024; Seedream defaults to 1536×1536. Send positive whole-pixel width and height to choose another size; the model's individual dimension bounds are published in its parameter schema. The reservation ceilings remain $0.075 and $0.117 respectively.

Models served by Replicate

These are billed at Replicate's published price for the render, pass-through, with no margin (Pricing & billing): the reservation is n × the model's per-image ceiling (Per image ≤), and the charge is the price below. They take aspect_ratio (or size) and resolution rather than quality.

Replicate counts FLUX.2's 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 up to 4 at the 1K sizes, 3 at 2048x1152 and 1152x2048, and 2 at 2048x1536, 1536x2048, 2048x2048 and auto. A larger n is refused with a 400 before anything renders, so it costs nothing.

Recraft models

Recraft models are served directly by Recraft and have IDs of the form recraft/<model>, such as recraft/recraftv4_1 or recraft/recraftv2_vector. They are billed at Recraft's published price, pass-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: accepts the 14 aspect ratios (1:1, 16:9, 6:10, …) on every model. 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.
  • The response's style_id can be reused.
  • 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, 10,000.
• V3 only: text_layout. controls takes colors and background_color on every model, plus artistic_level and no_text on V3.
• Seed: seed is passed 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

Bodies follow the OpenAI error envelope with the canonical class in error.metadata.error_type, and the class is on every failure in x-tm-error-code. A provider's own error body is never relayed; its status is in x-tm-upstream-status. The full taxonomy and remediation table is in Errors. For a failure after SSE begins, these details are in the terminal error event; the HTTP status can no longer change. See Final-image streaming.

The reverse refusal also holds: an image model sent to POST /v1/chat/completions, POST /v1/messages or POST /v1/decisions is a 400 invalid_request naming /v1/images/generations.

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, final routing headers are also returned in the completed event's response_headers extension.

Examples

curl -N --max-time 480 https://dev-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://dev-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 contains the provider's actual image bytes. Use event.output_format for a matching file extension when that metadata is available; otherwise inspect the file type.

curl -s https://dev-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://dev-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://dev-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)

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 so throughput stays measurable.

Model discovery

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

Every row of GET /v1/models carries architecture.output_modalities — ["text"], ["image"] or ["decisions"] — and the ?output_modalities= filter takes a comma list of those values. The public feed https://dev.routerplus.com/api/models.json carries output_modalities, the full supported_parameters descriptor map for image models, and max_output_tokens as the per-image ceiling. See GET /v1/models and Models & catalog.

BYOK

Image generation works through an openai provider connection. List the exact image ids you intend to send on the connection — matching is literal, and an id the connection does not carry is a 404 model_unavailable. The model's metadata (ceiling, descriptors) still comes from the house catalog. usage.cost is 0, the marketplace charge is zero, and OpenAI bills your own account for the render. See Bring your own key.

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