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. Google's Nano Banana family, ByteDance's Seedream and xAI's Grok Imagine are served through OpenRouter today and billed at the cost it reports — see Models billed at reported cost.

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, aspect_ratio, resolution, quality, background, moderation, output_format, output_compression and seed 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 — size on an OpenRouter model, quality on Nano Banana — 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.

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/videos is a 400 invalid_request naming /v1/images/generations.

Limits

Models billed at reported cost

The OpenRouter models are billed at the cost OpenRouter reports for the render, passed through with no margin (Pricing & billing).

• Reserve: n × the model's per-image ceiling, in USD — Per image ≤ on the models page.
• Settle: the reported cost, exactly. None reported: the ceiling, marked estimated.
• The response keeps OpenAI's shape. usage.input_tokens and usage.output_tokens are OpenRouter's own counts, for reading only; usage.cost is the charge.

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)

Content-free

Prompts and image bytes are content, and the marketplace never stores content. The prompt is never logged and never written to the ledger; the base64 bytes and any revised_prompt are relayed to you and dropped. Telemetry keeps the response byte size so throughput stays measurable, and nothing else. See Data policy.

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 ["video"] — 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