Image Generation

Generate and edit images through the OpenAI-compatible images endpoint when the selected model supports it.

POSThttps://onerouter.com/v1/images/generations

Troubleshooting

Running into an error while calling the API? See the Errors & Retries reference for a complete list of error types and troubleshooting steps.

Find an image model

See the Image Models page for usage guidance, then use the Models page or GET /v1/models to confirm the model IDs and capabilities available to your key.

Overview

The Image Generation endpoint is compatible with OpenAI's images API and creates images from a text prompt. Depending on the model, you can also edit or extend existing images by passing one or more source images.


You can call this endpoint in two ways: with application/json (reference images by URL or base64), or with multipart/form-data (upload binary files directly).

Request headers

ParameterTypeRequiredDescription
Authorizationstring · requiredrequiredBearer token authentication, formatted as `Bearer YOUR_API_KEY`.
Content-Typestring · requiredrequiredUse `application/json` when referencing image URLs; use `multipart/form-data` when uploading local files.

Routes

ParameterTypeRequiredDescription
/v1/images/generationsPOSTrequiredOpenAI-compatible image generation path.
/v1/images/editsPOSToptionalImage editing path when supported by the selected model/provider.
Chat/Responses image outputfeatureoptionalSome models generate images through Chat Completions or Responses using multimodal output parameters.

Request body

Common parameters for OpenAI-style image generation. Exact support, sizes, and quality tiers depend on the selected model — check the model detail page.

ParameterTypeRequiredDescriptionValues
modelstringrequiredImage model ID, e.g. `google/gemini-3-pro-image-preview` or `gpt-image-2`.
promptstringrequiredText description of the image to generate.
nintegeroptionalNumber of images to generate. Range depends on the model.
sizestringoptionalOutput dimensions or aspect ratio, e.g. `1024x1024` or `16:9` (model-dependent).
qualitystringoptionalQuality tier, e.g. `standard`, `hd`, or model tiers like `1k`/`2k`/`4k`.
response_formatstringoptionalHow images are returned: `url` or `b64_json` (model-dependent).
urlb64_json

Example request

curl https://onerouter.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-3-pro-image-preview",
    "prompt": "A calm mountain lake at sunrise, photorealistic",
    "n": 1,
    "size": "1024x1024"
  }'

Asynchronous models

Some image and video models run as background jobs and return a task ID, a polling URL, or a media URL instead of an inline image. That async lifecycle (submit → poll → result) is defined by the upstream model, not by a OneRouter-owned task API. Follow the response fields the model returns, and download returned media promptly — provider URLs can expire.

Billing

Image models are usually not billed like text-only models. Depending on the model, cost may be based on generated image count, resolution, quality, editing mode, or upstream-specific credits. Do not estimate image spend only from input/output tokens.

Model-dependent features

OneRouter keeps protocol compatibility and forwards model-specific parameters where supported. Features such as tool calling, structured output, reasoning, prompt caching, web search, image input, audio input, video generation, and provider-specific options depend on the selected model and upstream provider. Check the model detail page before relying on a feature in production.