Create images

Generates images from a text prompt, optionally with reference images for image-to-image. It is compatible with images.generate in the OpenAI Images API: the official OpenAI SDKs work once you set the Base URL to https://api.lyrouter.com/v1, and the image comes back in the same response, with no polling. Three families are available: Seedream 5.0, GPT-Image and Gemini Image. Parameters and the returned format differ by family; see the per-model sections below.

Authentication

Send your API key in a request header:

Authorization: Bearer <API Key>

Bearer is case-sensitive. You can use x-api-key: <API Key> instead; when both are present, only Authorization is read. Create API keys on the workspace's API Keys page. Your API key is used only to authenticate with LYRouter and is never forwarded to the upstream provider. See Base URLs and authentication.

Headers

Request body

The parameters shared by all models are listed below; whether each one takes effect for a given family is described in the model sections that follow.

Other parameters not in the table are forwarded unchanged to Seedream and GPT-Image, and whether they take effect depends on the model; Gemini drops all of them.

How each model is handled

The gateway decides per model how to handle the request body, which determines which parameters take effect:

• Pass-through: the body is forwarded unchanged with only the model name rewritten, so other parameters the provider supports can be sent as well. If the upstream does not accept a parameter, you get the upstream's own error.
• Contract translation: the gateway translates the parameters into the provider's format and drops those it cannot translate.
• Dropped parameters are listed in the X-Gateway-Unsupported-Parameters response header and the request still runs; with X-Gateway-Strict-Parameters: true it returns 400 instead. Parameters passed through to the upstream are not affected by this header.

For a comparison of model capabilities and use cases, see Multimodal capabilities. The model marketplace is authoritative for which models exist; the sections below list each family's parameters and limits.

Seedream 5.0 (pro / lite)

Seedream models on Volcengine Ark. Pass-through; returns an image URL by default; one generation takes about 20 s.

Reference image limits:

• Pro supports interactive editing: mark the position to change in the prompt with <point>x y</point> or <bbox>x1 y1 x2 y2</bbox> (coordinates normalized to 0–999).
• A layer decomposition response returns the base image and the layers together in data[], with fields such as z_index, bounding_box, name and description; each request reserves 17 images of rate-limit quota and returns the unused part when it completes. For the pixel sizes of each tier, coordinate conversion and reassembly, see Multimodal capabilities.
• Other Volcengine Ark parameters can be written directly in the body. With the OpenAI Python SDK, put them in extra_body, for example extra_body={"watermark": False}.

Billing: per image. Pro is tiered by resolution: 1K and 1.5K (≤ 2.61 megapixels) are one tier and 2K is another; layer decomposition has two more tiers (also split into 1K/1.5K and 2K) and is billed by the number of images actually produced (base image + each layer); pro reference images are billed as a separate item, with the first reference image in each request free and each additional one billed per image (this counts input reference images, not output images). Lite has a single tier. 1.5K costs the same as 1K and looks better, so prefer 1.5K unless you have a reason not to.

curl https://api.lyrouter.com/v1/images/generations \
  -H "Authorization: Bearer $LYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/doubao-seedream-5.0-lite",
    "prompt": "A shiba inu in sunglasses on a surfboard, sunset sea, cinematic, wide landscape composition",
    "size": "2K",
    "watermark": false
  }'

GPT-Image (2 / 2.5-flare / 2.5-sunburst)

Pass-through. Parameters match the OpenAI image API, and the result is always b64_json.

quality values:

Whether xhigh and max are available depends on the upstream account, so they may be rejected; if you get Invalid value: 'xhigh', use high instead.

The four hard constraints on size, checked by the provider; violating any one returns 400:

• Latency: one generation took about 20–60 s in measurements, occasionally longer (about 83 s at most); an upstream 400 caused by a bad parameter came back within 2 s. Set the client timeout in minutes, at least 300 s.

Billing: per token, with input text, input image and output priced separately; the upstream reports text and image tokens separately in usage.input_tokens_details, so a prompt of the same length costs a different amount with and without an image. Cache hits have their own price; usage from the 2.5 family has no cache fields, so that item does not occur for it.

Output tokens depend mainly on quality: at 1024x1024, the 2.5 family produces 196 output tokens at low and 7024 at max, so the top level is about 36 times the bottom one. A level with the same name is not the same amount on the two generations: high on the 2.5 family produces as many output tokens as medium on gpt-image-2, so compare models by tokens, not by level name. Also, for GPT-Image more pixels do not mean a higher cost (this applies to GPT-Image only): output tokens do not grow with pixel count; for example, 1024x1536 (about 1.57 million pixels) produces fewer output tokens than 1024x1024 (about 1.05 million pixels).

Gemini Image (3 Pro / 3.1 Flash)

Contract translation: the gateway translates the request into Gemini's native generateContent format, uses only the parameters marked as applied below, and drops the rest, listing them in the response header. The result is always b64_json and cannot be a URL. One generation took 20–250 s in measurements (gemini-3-pro-image), and occasionally had not returned after 300 s.

How you write size determines the aspect ratio and the resolution:

The provider rejects the 512 tier in production, on both models; do not use it.

Supported aspect ratios: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, 1:4, 4:1, 1:8, 8:1. When you write a width and height, the tier is picked by rounding the long edge up, capped at 4K; a long edge of 704 or less is mapped to 512 by the gateway and may be rejected as well, so keep the long edge above 704. The same tier produces different output tokens on the two models:

The output size is chosen by the provider from the ratio and resolution tiers and does not equal the requested width and height; for example, gemini-3-pro-image returns a 5504x3072 image for a 4096x2304 request. Rely on the actual width and height of the returned image.

For example, 1024x1024 maps to 1:1 + 1K, and 2048x2048 maps to 1:1 + 2K. For 16:9 at 4K, write 4096x2304; do not copy 5632x3072: its ratio is 1.833, more than 2% off 16:9, so the whole size is dropped. In production, send X-Gateway-Strict-Parameters: true so that such a request returns 400 instead.

Billing: per token, with input, output and thinking priced separately; reference images count toward "input". Thinking tokens appear only when the upstream returns them (gemini-3-pro-image), in usage.output_tokens_details.reasoning_tokens, and usage.total_tokens includes them. Thinking tokens vary from call to call and are decided by the model: production measurements range from 115 to 316, with a median of about 220, about 1.5% of a call's cost. Budget about 220 per call.

{
  "data": [{ "b64_json": "iVBORw0KGgoAAAANSUhEUgAA…" }],
  "usage": {
    "input_tokens": 7,
    "output_tokens": 1120,
    "total_tokens": 1339,
    "output_tokens_details": { "reasoning_tokens": 212 }
  }
}

Request examples

The examples below use openai/gpt-image-2 and save the returned Base64 image to a file. With Seedream, the image comes back as a URL by default: read data[0].url and download it promptly.

curl https://api.lyrouter.com/v1/images/generations \
  --max-time 300 \
  -H "Authorization: Bearer $LYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "A shiba inu in sunglasses on a surfboard, sunset sea, cinematic",
    "size": "1024x1024",
    "quality": "medium"
  }'

import base64
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LYROUTER_API_KEY"],
    base_url="https://api.lyrouter.com/v1",
    timeout=300,
)
result = client.images.generate(
    model="openai/gpt-image-2",
    prompt="A shiba inu in sunglasses on a surfboard, sunset sea, cinematic",
    size="1024x1024",
    quality="medium",
)
with open("shiba.png", "wb") as f:
    f.write(base64.b64decode(result.data[0].b64_json))
print(result.usage)

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

const client = new OpenAI({
  apiKey: process.env.LYROUTER_API_KEY,
  baseURL: "https://api.lyrouter.com/v1",
  timeout: 300_000,
});
const result = await client.images.generate({
  model: "openai/gpt-image-2",
  prompt: "A shiba inu in sunglasses on a surfboard, sunset sea, cinematic",
  size: "1024x1024",
  quality: "medium",
});
writeFileSync("shiba.png", Buffer.from(result.data[0].b64_json, "base64"));
console.log(result.usage);

Response

A successful request returns an object in the OpenAI Images format, with the images in the top-level data array; an error returns an error object. The two 200 examples below are Seedream (returning a URL) and GPT-Image (returning Base64); the 400 is Gemini receiving parameters it does not support with strict mode on; the 403 means the model is not enabled, or a virtual model or Auto was used.

{
  "model": "doubao-seedream-5-0-260128",
  "created": 1789454321,
  "data": [
    {
      "url": "https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/…",
      "size": "1920x1920"
    }
  ],
  "usage": {
    "generated_images": 1,
    "output_tokens": 14400,
    "total_tokens": 14400
  }
}

{
  "created": 1791950400,
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA…" }
  ],
  "size": "1024x1024",
  "quality": "medium",
  "output_format": "png",
  "background": "opaque",
  "usage": {
    "input_tokens": 29,
    "input_tokens_details": { "text_tokens": 29, "image_tokens": 0 },
    "output_tokens": 1756,
    "total_tokens": 1785
  }
}

{
  "error": {
    "message": "unsupported parameters for this model: n,quality",
    "type": "invalid_request_error",
    "code": "unsupported_parameters"
  }
}

{
  "error": {
    "message": "Model is not available in the model plaza",
    "type": "access_denied",
    "code": "model_not_available"
  }
}

Fields in usage

Do not assume a field is always present; check before reading it. For how each model is billed, see the model sections above; prices are those shown in the model marketplace in the console, and the actual charge for each call is in the request logs.

Response headers

When quotas are configured, the response also carries the x-aigw-quota-* headers; see Gateway headers and extensions.

To read the dropped parameters (the Python and Node.js examples reuse client from the examples above):

curl -sS -D - -o result.json https://api.lyrouter.com/v1/images/generations \
  --max-time 300 \
  -H "Authorization: Bearer $LYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"google/gemini-3.1-flash-image","prompt":"A single green leaf, flat design","size":"1376x768","n":2}'
# The response headers include: X-Gateway-Unsupported-Parameters: n

raw = client.images.with_raw_response.generate(
    model="google/gemini-3.1-flash-image",
    prompt="A single green leaf, flat design",
    size="1376x768",
    n=2,
)
print(raw.headers.get("X-Gateway-Unsupported-Parameters"))  # n
result = raw.parse()

const { data: result, response } = await client.images
  .generate({
    model: "google/gemini-3.1-flash-image",
    prompt: "A single green leaf, flat design",
    size: "1376x768",
    n: 2,
  })
  .withResponse();
console.log(response.headers.get("X-Gateway-Unsupported-Parameters")); // n

Gateway behavior

Compared with calling the upstream directly, calling through LYRouter differs in these ways:

• Only the requested model is used: image endpoints never switch to another model. When the same model has several channels, the gateway tries the other channels in turn after a failure; virtual models, Auto smart routing and fallback to the workspace's Default Model do not apply to image endpoints. See Retries and fallback.

• Dropped parameters and strict mode: the gateway drops only the parameters listed in "How each model is handled" above and lists them in the X-Gateway-Unsupported-Parameters response header. In production, check this header, or send X-Gateway-Strict-Parameters: true so that a request containing a parameter that would be dropped returns 400 immediately, without calling the upstream and without charge. With the SDKs, pass it as extra_headers={"X-Gateway-Strict-Parameters": "true"} (Python) or the request option { headers: { "X-Gateway-Strict-Parameters": "true" } } (Node.js). Parameters passed through to the upstream are not affected by this header; the upstream decides whether to accept them.

• Errors declared in a successful upstream response: when Gemini's upstream rejects a request, it may return HTTP 200 with no image. The gateway rewrites this into an error response, taking the status code from the error the upstream declared: when the upstream rejected the request, error.code is upstream_rejected and error.message is the upstream's original text; when no image was produced, the code is upstream_no_artifact with upstream_finish_reason (such as NO_IMAGE or SAFETY). upstream_status keeps the upstream's original 200. These errors are not retried on another channel; change the prompt or parameters as indicated:

  Copy code

  {
    "error": {
      "message": "upstream produced no image (finishReason: NO_IMAGE)",
      "type": "invalid_request_error",
      "code": "upstream_no_artifact",
      "upstream_status": 200,
      "upstream_finish_reason": "NO_IMAGE",
      "generated_by": "ai-gateway"
    }
  }
  

• Upstream errors are returned unchanged: parameter errors for pass-through models come from the upstream, with the upstream's format and error codes; Seedream, for example, returns {"error":{"code":"InvalidParameter","message":"..."}}. When the upstream returns an error status with no body, the gateway fills in an error body with upstream_status and generated_by: "ai-gateway", plus upstream_request_id when the upstream supplied a request ID; give that ID to the provider when reporting an issue.

• Images are not stored in logs: Base64 images in requests and responses are replaced in the logs with a [base64 <bytes>B #<CRC32>] summary. Not seeing the image in the log details does not mean the request failed; the image is in the response body. For models that return a URL, the URL is kept in the logs.

• Timeouts: image endpoints are synchronous. Seedream takes about 20 s, the GPT-Image family about 20–60 s in measurements, and Gemini 20–250 s in measurements, occasionally more than 300 s. Set the client timeout in minutes, at least 300 s, rather than the 30 s you use for text; after a client timeout, do not resubmit right away; first check the result of the previous request in the request logs.

Common errors

Errors returned by the gateway take the form {"error":{"message":"...","type":"...","code":"..."}}; parameter errors for pass-through models come from the upstream in the upstream's format.

• For 401 / 403 authentication issues, see 401 / 403: authentication and access; for 429, see 429: rate limits and quotas.
• 500 / 504 mean the connection to the upstream failed or the wait for the upstream timed out; the response body is an HTML page rather than JSON. See Timeouts and interrupted streams.
• For the full list, see Errors and request identifiers.