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.

The route is deliberately small: generations only (no edits, no variations), non-streaming, and the image always comes back as base64 in the body. Everything else is a typed error, never a silent degradation. 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

style and any key not in the table 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

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.

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.

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.

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.

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.

Examples

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