Console
API reference

Images

Generate images.

POST/v1/images/generations

Generate images from a text prompt. This is the OpenAI Images API surface: point client.images.generate at https://api.routerplus.com/v1 and the call works unchanged. The path https://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.

Note

Not supported: OpenAI's client.images.edit (POST /v1/images/edits) and client.images.create_variation (POST /v1/images/variations). Both paths are a 404 not_found. Models that take reference images take them on this route: see How to edit an image.

By default the route returns one JSON response, and existing clients need no change for a render that takes minutes (see Long-running JSON requests). Optional stream: true returns keep-alives followed by one final image event. Images always come back as base64; streaming does not enable partial previews.

Image models come from these providers:

ProviderModel idsBilled
OpenAI directthe GPT Image models, such as gpt-image-2in tokens — see Billing
Replicatebare ids, such as nano-banana-pro and flux-2-proat Replicate's published price — see Models served by Replicate
Kreakrea/…, such as krea/krea-3at Krea's published price — see Krea image models
Recraftrecraft/…, such as recraft/recraftv4_1at Recraft's published price — see Recraft models
MachGenmachgen/…, such as machgen/nano-banana-proat what MachGen bills for the render — see MachGen models
Bitdeer AIbitdeer/seedream-5.0-liteat Bitdeer's published price — see Bitdeer models

Authentication

HeaderFormat
AuthorizationBearer tm_vk_... (the standard OpenAI-style header)
x-api-keytm_vk_... — also accepted, same key

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.

ParameterTypeBehavior
modelstring, requiredAn image model id — see Model discovery. A dated pin (-20260421, -2026-04-21, -latest) resolves to its catalog family for routing and pricing, and your exact string goes upstream. A chat model here is a 400 naming the chat routes; a decision model a 400 naming /v1/decisions. An id that is not an image model anywhere is a 404. Omitted or empty is a 400 naming model.
promptstring, requiredNon-empty, at most 32 000 characters.
nintegerPer model, as supported_parameters.n declares: 1 to 4 on the GPT Image models and wan-2.7-image-pro, 1 to 6 on the Recraft models, and 1 on every other model. Defaults to 1. Ours is stricter than the SDK's 10: four buffered images already approach the response cap.
sizestringauto, 1024x1024, 1536x1024 or 1024x1536 on the GPT Image models.
qualitystringauto, low, medium, high — plus xhigh and max on gpt-image-2.5-flare and gpt-image-2.5-sunburst.
backgroundstringauto, transparent, opaque on the GPT Image models.
moderationstringauto or low on the GPT Image models.
output_formatstringpng, jpeg or webp on the GPT Image models.
output_compressioninteger0 to 100 on the GPT Image models.
userstringForwarded verbatim. Anything but a string is a 400.
response_formatstringb64_json only, and it is a no-op. url is a 400 — see Always base64.
streambooleantrue opts into final-image SSE and requires n: 1. Absent, null, or false returns the ordinary JSON response.
partial_imagesintegerAbsent, null, or 0 only. Partial previews are not supported; other values return 400 before dispatch.
providerobjectRouting controls read by the gateway and never forwarded — require_parameters and the rest, see Routing policies.

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. A GPT Image model:

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

A model billed at the provider's reported cost (every image model but the GPT Image models) answers in the same shape. Its usage keeps the provider's own token counts, 0 when the provider reports none, and usage.cost is the charge. seedream-5-lite on Replicate, $0.035 an image:

json
{
  "created": 1790000000,
  "data": [{ "b64_json": "/9j/4AAQSkZJRgABAQAAAQABAAD..." }],
  "output_format": "jpeg",
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0,
    "cost": 0.035
  }
}
FieldMeaning
data[].b64_jsonThe image, base64-encoded. One entry per image the provider rendered — normally n; the gateway relays what it received and bills what was reported.
data[].revised_promptThe provider's rewritten prompt, when it sends one. Relayed in the response. See Data policy.
output_formatThe image's format, when known: OpenAI's own field on the GPT Image models; on the other models read from the image's bytes (png, jpeg, webp, or svg from a Recraft vector model).
usage.input_tokensGPT Image: prompt tokens, billed at the model's prompt rate. Reported-cost models: the provider's own count, for information only, and not billed.
usage.output_tokensGPT Image: image output tokens, billed at the model's completion rate. Reported-cost models: the provider's own count, for information only, and not billed.
usage.input_tokens_detailsInformational only — the bill is computed from the two counts above.
usage.total_tokensinput_tokens + output_tokens.
usage.costUSD, the full request debit including any attempt that failed over before this one. 0 on BYOK. Absent on static dev keys.

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 600 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: normal JSON uses the edge relay described above. Neither transport extends the generation budget or guarantees that a provider completes in time.

Note

A 200 that reports no usage is billed what the reservation held, with provenance estimated. On a GPT Image model that is a 200 without a usage object, or with input_tokens and output_tokens both 0: the gateway bills n × the model's per-image ceiling and writes those numbers into usage, so your copy of the bill still adds up. On a model billed at the provider's reported cost it is a 200 without usage.cost: the gateway bills n × the per-image ceiling, and usage.cost shows that amount. The provenance is visible at GET /v1/generation.

Billing

Image models bill in one of two ways, with the same integer micro-USD math as chat (Pricing):

  • The GPT Image models bill in tokens, on the same two SKUs as chat: text in bills at prompt, image out bills at completion.

  • Every other image model bills the cost reported for the render, at the provider's published price with no margin (see Models billed at the provider's reported cost). Its prices are 0 in and 1 out per million cost units, one unit a micro-dollar, so the two rules below hold n × its per-image ceiling and settle the reported cost exactly.

  • 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, or on the reported cost. The hold is released in full. A reported cost above the hold is still charged in full: the ceiling limits what is held, not what is billed.

Worked numbers on gpt-image-2 (ceiling 8,232 tokens, $5 / $30 per million):

CaseAmount
Reserve, n: 18,232 × $30/M ≈ $0.247, plus the prompt estimate
Reserve, n: 44 × 8,232 × $30/M ≈ $0.988, plus the prompt estimate
Settle, one low 1024×1024 image196 × $30/M = $0.00588, plus the prompt
Settle, one medium 1024×1024 image1,756 × $30/M = $0.05268, plus the prompt

OpenAI counts an image's output tokens from its size and quality; the counts above are the ones OpenAI reports for gpt-image-2.

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.

Warning

Reservations are large next to a trial balance. n: 4 at a high quality holds about a dollar, and your balance must cover every reservation your org has in flight. A 429 insufficient_quota on n: 4 is correct behavior, not a bug — lower n, or add credits.

GPT Image models

Served by OpenAI direct and billed in tokens, at OpenAI's price:

Model idText in /1MImage out /1MPer-image ceiling
gpt-image-2$5$308,232 tokens
gpt-image-2.5-flare$5$308,232 tokens
gpt-image-2.5-sunburst$5$308,232 tokens
gpt-image-1.5 (until 2026-12-01)$5$326,500 tokens
gpt-image-1-mini (until 2026-12-01)$2$86,500 tokens

They take n from 1 to 4 and the OpenAI parameters in Request. OpenAI shut down gpt-image-1 on 2026-10-23, and shuts down gpt-image-1-mini and gpt-image-1.5 on 2026-12-01 (OpenAI's deprecations); they leave the catalog on those dates. Use gpt-image-2 or a gpt-image-2.5 model.

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.

json
{
  "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 thinking and 4K output are not offered: Krea publishes no API price for them. 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 take an image URL, or an inline PNG, JPEG or WebP data URI that the gateway uploads the same way.

Krea 3 charges Krea's published price for each image:

Krea 3Price
resolution: "1k"$0.03 per image
resolution: "2k"$0.06 per image
thinking_mode: "high"adds $0.02
Each reference up to 1,048,576 pixels (1024×1024)adds $0.02
Each larger referenceadds $0.07

The gateway reads each inline reference's size from the image itself. With five or more references, Krea fits each one to 1536 px on its long side first, and the gateway measures it the same way. A reference sent as a URL is not measured, so it adds $0.07. A request with width and height instead of resolution costs the 1K or 2K price of the canvas Krea renders. For example, a 2K edit with one 1024×1024 reference and high thinking costs $0.06 + $0.02 + $0.02 = $0.10. The most one Krea 3 image can cost is $0.64 (2K, high, eight larger references); that is what the gateway holds while it renders.

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:

ModelLower tier, inclusiveAbove that areaReferences
Qwen Image 3≤1,048,576 pixels: $0.04$0.075Up to 3; included in the price
Seedream 5 Pro≤2,359,296 pixels: $0.045$0.09Up to 10; first included, then $0.003 each

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.

Every Krea model, with its main parameters and Krea's price per image. Per image ≤ is the most one image can cost, which the gateway holds while it renders:

Model idMain parametersPricePer image ≤
krea/krea-3resolution, thinking_mode, aspect_ratio or width + height, image_urls (up to 8), regional_edit, negative_prompt, seed$0.03 at 1K, $0.06 at 2K, plus high thinking and references (above)$0.64
krea/krea-2-largeaspect_ratio, resolution, image_url + strength, image_style_references, moodboards, styles, creativity, seed$0.06; $0.065 with image_style_references; $0.07 with a moodboard$0.07
krea/krea-2-mediumas Krea 2 Large$0.03; $0.035; $0.04$0.04
krea/krea-2-turboas Krea 2 Large$0.015; $0.0175; $0.02$0.02
krea/google/nano-banana-2.1resolution (1K, 2K, 4K), aspect_ratio, width, height, image_urls, thinking_level$0.03 at 1K, $0.0505 at 2K, $0.0755 at 4K$0.0755
krea/ideogram/ideogram-4.5quality, aspect_ratio, resolution, image_urls (up to 5), preserve_source_size, seed$0.008 very_low, $0.03 low, $0.06 medium, $0.10 high; $0.22 high with image_urls$0.22
krea/ideogram/ideogram-4.5-preciseimage_url (required), mask_url, reference_images (up to 4, or 3 with a mask), quality, seed$0.008 very_low, $0.03 low, $0.06 medium, $0.22 high$0.22
krea/recraft/recraft-v4.1-flashaspect_ratio, resolution$0.007$0.007
krea/alibaba/qwen-image-3width + height, style_images (up to 3), seed$0.04 up to 1,048,576 pixels, $0.075 above$0.075
krea/alibaba/qwen-image-2.1width + height, style_images (up to 3), background, seed$0.04$0.04
krea/bytedance/seedream-5-prowidth + height, style_images (up to 10), seed$0.045 up to 2,359,296 pixels, $0.09 above; $0.003 per reference after the first$0.117
krea/bytedance/seedream-5-litewidth + height, style_images (up to 14), seed$0.035$0.035
krea/meta/muse-imageaspect_ratio, style_images (up to 10)$0.01$0.01
krea/luma/uni-1width + height, mode, style, style_images (up to 9)$0.0404 in standard mode, $0.10 in max; $0.003 per reference$0.127
krea/xai/grok-imagine-2quality, resolution, aspect_ratio, style_images (up to 3)$0.04 at low and 1K; $0.02 more for medium, $0.02 more for 2K; $0.01 per reference$0.11
krea/xai/grok-imagine-2-editimage_urls (1 to 3, required), quality, resolutionas Grok Imagine 2.0, each image_urls entry a reference$0.11

Qwen Image 3, Qwen Image 2.1, Seedream 5 Pro and Seedream 5 Lite send seed: 1337 when you send no seed. The same prompt and settings then usually give the same image: send another seed for a different one.

Models served by Replicate

These are billed at Replicate's published price for the render, pass-through, with no margin (Pricing): the reservation is n × the model's per-image ceiling (Per image ≤), and the charge is the price below. Only wan-2.7-image-pro takes size. The others take aspect_ratio, and most take resolution; none takes quality. OpenAI's size or quality sent to a model that does not declare it is dropped and named in x-tm-dropped-params, and the image renders at the model's defaults. To get a 400 instead, send "provider": {"require_parameters": true}.

Model idMade byShapeListed pricePer image ≤
nano-banana-proGoogleaspect_ratio; resolution 1K, 2K, 4K$0.15 at 1K or 2K, $0.30 at 4K$0.30
nano-banana-2Googleaspect_ratio; resolution 1K, 2K, 4K$0.067 at 1K, $0.101 at 2K, $0.151 at 4K$0.151
nano-banana-2-liteGoogleaspect_ratio$0.034$0.034
nano-bananaGoogleaspect_ratio$0.039$0.039
flux-2-maxBlack Forest Labsaspect_ratio; resolution 0.5MP, 1MP, 2MP, 4MP; seed$0.04 a render + $0.03 per output megapixel$0.19
flux-2-proBlack Forest Labsas flux-2-max$0.015 a render + $0.015 per output megapixel$0.09
flux-2-flexBlack Forest Labsas flux-2-max$0.06 per output megapixel$0.30
flux-2-klein-4bBlack Forest Labsaspect_ratio; resolution 0.25MP, 0.5MP, 1MP, 2MP, 4MP; seed$0.001 per output megapixel$0.005
flux-3-imageBlack Forest Labsaspect_ratio; resolution 768, 1K, 1.5K, 2K, 4K$0.0205 at 768, $0.024 at 1K, $0.035 at 1.5K, $0.05 at 2K, $0.3035 at 4K$0.3035
seedream-5-liteByteDanceaspect_ratio; resolution 2K, 3K$0.035$0.035
seedream-4.5ByteDanceaspect_ratio; resolution 2K, 4K$0.04$0.04
grok-imagine-imagexAIaspect_ratio$0.02$0.02
grok-imagine-image-qualityxAIaspect_ratio; resolution 1K, 2K$0.05 at 1K, $0.07 at 2K$0.07
wan-2.7-image-proAlibabasize (10 exact sizes up to 2048x2048, or auto); n up to 4, at most two 2048x2048 images' pixels per answer; seed$0.03$0.03
qwen-image-3-proAlibabaaspect_ratio; seed$0.04$0.04

Replicate counts the FLUX.2 models' output megapixels in whole megapixels, rounded up: a 0.5MP render bills as 1. Prices were read from Replicate between 2026-10-12 and 2026-10-17.

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.

FamilyRasterVectorPro raster (2K)Pro vector
V4.1 Flashrecraft/recraftv4_1_flash: $0.007———
V4.1recraft/recraftv4_1: $0.035recraft/recraftv4_1_vector: $0.08recraft/recraftv4_1_pro: $0.21recraft/recraftv4_1_pro_vector: $0.30
V4.1 Utilityrecraft/recraftv4_1_utility: $0.035recraft/recraftv4_1_utility_vector: $0.08recraft/recraftv4_1_utility_pro: $0.21recraft/recraftv4_1_utility_pro_vector: $0.30
V4 Stylesrecraft/recraftv4_styles: $0.035recraft/recraftv4_styles_vector: $0.05recraft/recraftv4_styles_pro: $0.10recraft/recraftv4_styles_pro_vector: $0.12
V4recraft/recraftv4: $0.04recraft/recraftv4_vector: $0.08recraft/recraftv4_pro: $0.25recraft/recraftv4_pro_vector: $0.30
V3recraft/recraftv3: $0.04recraft/recraftv3_vector: $0.08——
V2recraft/recraftv2: $0.022recraft/recraftv2_vector: $0.044——

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.
json
{
  "model": "recraft/recraftv4_styles_vector",
  "prompt": "a lighthouse on a cliff",
  "size": "16:9",
  "style_reference_urls": ["https://example.com/brand-reference.png"]
}

MachGen models

MachGen runs FLUX.2 Dev and HiDream O1 on its own GPUs and serves the others from their makers. Their ids are machgen/<model>. They are their own listings, not other routes of the same models served elsewhere (nano-banana-pro on Replicate, gpt-image-2 on OpenAI): name the machgen/ id to use MachGen.

Model idShapeEdits (image_urls)List priceYou pay
machgen/nano-banana-proaspect_ratio (9) and resolution 1K, 2K; seedup to 14$0.079 at 1K or 2K$0.06715
machgen/nano-banana-2as Nano Banana Proup to 14$0.04 at 1K, $0.048 at 2K$0.034, $0.0408
machgen/nano-banana-2.1as Nano Banana Pro, no seedup to 14$0.04 at 1K, $0.048 at 2K$0.04, $0.048
machgen/seedream-5-litesize: 12 sizes from 2048x2048 to 5504x3040up to 14$0.038$0.0323
machgen/gpt-image-2size: 22 sizes from 1280x544 to 3840x2160; quality high or lowup to 16$0.048 to $0.252 (high), $0.0014 to $0.0071 (low)85% of list
machgen/gpt-image-2.5-sunburstsize: the same 22up to 16$0.066 to $0.35385% of list
machgen/gpt-image-2.5-flaresize: the same 22up to 16$0.066 to $0.35385% of list
machgen/grok-imagine-imageaspect_ratio (4) and resolution 1K, 2K—$0.024$0.0204
machgen/grok-imagine-image-qualityas Grok Imagine Imageup to 3$0.059 at 1K, $0.083 at 2K$0.05015, $0.07055
machgen/flux-2-devsize: 1024x1024, 1024x768, 1024x1808, 2048x1536, 2048x2048; seedup to 3$0.004 per megapixel$0.004 per megapixel
machgen/hidream-o1-imagesize: as FLUX.2 Dev; seed—$0.003 per megapixel$0.003 per megapixel
  • What you pay. What MachGen bills us, with no margin: its list price less the credit-back it gives on that model. That is 15% on most models. Nano Banana 2.1, FLUX.2 Dev and HiDream O1 get no credit-back from MachGen, so they are at list. The You pay column shows it. The price is fixed per size and setting, so you know the charge before the render: exact prices for every size are on each model's page and in /api/models.json. A per-megapixel model is priced for each of its sizes at its exact megapixels. The playground's estimate, and the credit held while a render runs, is the model's highest price, not the price of the size you picked; you are charged the price of what you asked for.
  • No 4K on Nano Banana. MachGen offers it, but a detailed 4K PNG is larger than the 32 MiB answer limit, so resolution takes 1K and 2K. 4K is refused with a 400 before anything is reserved.
  • References are links. image_urls takes public https URLs. MachGen fetches each one itself; an inline data URI is refused with a 400 before anything is reserved. A model without edits drops image_urls and names it in x-tm-dropped-params.
  • The prompt is rendered as sent. MachGen can rewrite a prompt before rendering it. It does not unless you send enhance_prompt: true.
  • One image per request (n is 1). quality is GPT Image 2's only: high is MachGen's standard level, low its express level.
  • Moderation. A render MachGen's moderation refuses is a 400 content_policy, billed nothing.
  • Request data. MachGen keeps prompts and outputs for a period it sets, and forwards partner-served requests to the model's maker (Google, OpenAI, ByteDance, xAI).
  • Prices were read from MachGen's pricebook on 2026-11-09.
json
{
  "model": "machgen/nano-banana-pro",
  "prompt": "Put the mug on a wooden desk by a window, morning light",
  "aspect_ratio": "4:3",
  "resolution": "2K",
  "image_urls": ["https://example.com/mug.png"]
}

Bitdeer models

Bitdeer AI serves Seedream 5.0 Lite. Its id is bitdeer/seedream-5.0-lite: its own listing, not another route of seedream-5-lite (Replicate) or machgen/seedream-5-lite (MachGen).

Model idShapeYou pay
bitdeer/seedream-5.0-litesize 2K (2048x2048, the default), 3K (3072x3072), 4K (4096x4096); seed$0.035 per image, at every size
  • One image per request (n is 1).
  • Request data. Seedream is ByteDance's model; Bitdeer's own terms cover what it keeps.
  • The price was read from Bitdeer's pricing page on 2026-11-16.
json
{
  "model": "bitdeer/seedream-5.0-lite",
  "prompt": "A watercolor painting of a lighthouse at dawn",
  "size": "2K"
}

How to edit an image

There is no edits endpoint. To change an image, send it to POST /v1/images/generations with a model that takes a source image, in that model's own parameter:

ModelSend the image inWhat it does
krea/krea-3image_urls (up to 8)Edits or combines the images as the prompt says. Add regional_edit: true for a regional edit (experimental).
krea/xai/grok-imagine-2-editimage_urls (1 to 3, required)Edits the images as the prompt says.
krea/ideogram/ideogram-4.5-preciseimage_url (required), and mask_urlEdits the source image. A mask the size of the source selects the region: white is edited, black is kept.
krea/ideogram/ideogram-4.5image_urls (up to 5)Edits from source or reference images, as the prompt says.
krea/google/nano-banana-2.1image_urlsImage prompts that the prompt can change or combine.
krea/krea-2-large, krea/krea-2-medium, krea/krea-2-turboimage_url, with strengthStarts from the image instead of noise. strength 0 keeps it, 1 replaces it (default 0.99).
MachGen's Nano Banana, Seedream 5.0 Lite, GPT Image, Grok Imagine Image Quality and FLUX.2 Devimage_urls, public https URLs (see MachGen models)Edits or combines the images as the prompt says.
json
{
  "model": "krea/ideogram/ideogram-4.5-precise",
  "prompt": "Replace the sky with a sunset.",
  "image_url": "https://example.com/photo.png",
  "mask_url": "https://example.com/sky-mask.png"
}

Other models take reference images that steer a new image rather than edit one: style_images on Krea's Qwen, Seedream, Muse, Luma UNI-1 and Grok Imagine 2.0 models, image_style_references on Krea 2, and style_reference_urls on the Recraft models, which set a style. The GPT Image models and the models served by Replicate take no image on this route.

On the Krea and Recraft models, a reference is an image URL or an inline PNG, JPEG or WebP data URI, inside the 10 MB request limit; Krea 3 takes only an inline image or a Krea asset URL. References can change the price: see each model's row above. GET /v1/models lists "image" in architecture.input_modalities for every model that takes one, and /api/models.json publishes each parameter's schema under supported_parameters. A reference parameter that a model does not declare is dropped and named in x-tm-dropped-params, like any other undeclared key.

Errors

CaseStatuserror_typeBilled
A field outside the model's accepted values, n outside the model's limits, stream: true with n other than 1, nonzero partial_images, response_format: "url", a chat or decision model on this route400invalid_requestno row
The model is listed but has no price row400model_not_pricedno row
Not an image model in the catalog404model_unavailableno row
Request body over 10 MB413request_too_largeno row
Key RPM or a shared limit, balance too low, or a monthly spend cap429rate_limit / insufficient_quotano row
A moderation refusal (moderation_blocked) from OpenAI, or from a model served by Replicatethe provider's, usually 400content_policy$0; never rerouted, never a health strike
Any other provider 4xxthe provider'supstream_error$0; no failover
Provider 5xx, a failed connection, or the 450 s budget5xx relayed / 502 / 504upstream_error / model_unavailable$0 per failed attempt; fails over like chat
Response over the 32 MiB cap502gateway_error$0; no failover
A 200 that is unparseable or has no b64_json502upstream_error$0; no failover
The budget ran out while reading the image body504upstream_error$0; no failover
Every deployment serving the model is cooling down503gateway_errornothing dispatched; retry-after: 5
The ledger journal, the shared limit store, or the admission lease is unavailable503gateway_errornothing charged

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

LimitValue
Images per requestJSON: the model's own n limit (4 on the GPT Image models and wan-2.7-image-pro, 6 on the Recraft models, 1 on the rest); SSE: n = 1
Prompt length32 000 characters
Request body10 MB → 413 request_too_large
Upstream response32 MiB → 502 gateway_error, nothing billed.
Generation budget600 s, covering the body read as well as the render
StreamingOpt-in final-image SSE; no partial previews
Admissionone slot held for the whole render (10 seconds to several minutes)
ProvidersOpenAI direct for the GPT Image models — never Azure, Bedrock or an Anthropic deployment; Replicate, Krea, Recraft or MachGen for every other model

Response headers

HeaderWhenMeaning
x-request-idevery callthe id GET /v1/generation?id= audits
x-tm-providerserved requestsdeployment that rendered the image
x-tm-attemptsafter ≥ 1 dispatchphysical dispatches, failovers included
x-tm-upstream-statuswhen a provider answeredthe provider's own HTTP status
x-tm-dropped-paramswhen non-emptycomma-joined names of parameters the gateway stripped
x-tm-upstream-modelwhen the route knows the model by another idthe id the gateway actually sent
x-tm-served-bywhen a route reports onethe provider that ran the request
x-tm-route-plan-idbilled requeststhe route plan that chose the deployment
x-tm-admission-mode, x-tm-remaining-rpm, x-tm-remaining-tpmbilled requestshow the request was admitted and the headroom left — see Limits and capacity
x-tm-error-codeevery failurethe canonical error class
x-tm-error-origin, x-tm-limit-scope, x-tm-limit-kindlimit, provider and infrastructure failureswhere it came from, and the limit that refused it

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
Keep a slow Qwen render connected and print its final SSE event
curl -N --max-time 630 https://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}'
python
Consume the final image through the official OpenAI SDK, with automatic retries disabled so a lost response does not submit another render
import base64
import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    base_url="https://api.routerplus.com/v1",
    api_key=os.environ["TM_API_KEY"],
    timeout=630.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
Decode the first image straight to a file
curl -s https://api.routerplus.com/v1/images/generations \
  -H "Authorization: Bearer $TM_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"a red bicycle on a white background","size":"1024x1024","quality":"medium"}' \
  | jq -r '.data[0].b64_json' | base64 -d > out.png
python
The official openai SDK with the base URL swapped. The client waits 630 seconds, longer than the gateway's 600-second budget, and never retries on its own, because a retry after a lost response can pay for a second render
import base64
import os
from openai import OpenAI

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

r = client.images.generate(
    model="gpt-image-2",
    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
typescript
The official openai package, with the same timeout (in milliseconds) and no retries
import { writeFileSync } from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.routerplus.com/v1",
  apiKey: process.env.TM_API_KEY,
  timeout: 630_000,
  maxRetries: 0,
});

const r = await client.images.generate({
  model: "gpt-image-2",
  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

bash
curl -s "https://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"], ["video"] or ["decisions"] — and the ?output_modalities= filter takes a comma list of those values. An image model that takes reference images lists ["text", "image"] in architecture.input_modalities. The public feed https://app.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: in tokens on the GPT Image models, in micro-dollars on the models billed at the provider's reported cost, whose rows also carry "billing": "reported_cost" and the provider's prices in price_card. See GET /v1/models and Models.

BYOK

Image generation works through an openai provider connection, for the GPT Image models only: every other image model has no BYOK connection and always bills your RouterPlus balance. 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 · Pricing · Errors · Wire compatibility

For agents: /docs/api-images.md and /llms.txt