Image Generation
Generate and edit images through the OpenAI-compatible images endpoint when the selected model supports it.
https://onerouter.com/v1/images/generationsTroubleshooting
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
| Parameter | Type | Required | Description |
|---|---|---|---|
| Authorization | string · required | required | Bearer token authentication, formatted as `Bearer YOUR_API_KEY`. |
| Content-Type | string · required | required | Use `application/json` when referencing image URLs; use `multipart/form-data` when uploading local files. |
Routes
| Parameter | Type | Required | Description |
|---|---|---|---|
| /v1/images/generations | POST | required | OpenAI-compatible image generation path. |
| /v1/images/edits | POST | optional | Image editing path when supported by the selected model/provider. |
| Chat/Responses image output | feature | optional | Some 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.
| Parameter | Type | Required | Description | Values |
|---|---|---|---|---|
| model | string | required | Image model ID, e.g. `google/gemini-3-pro-image-preview` or `gpt-image-2`. | |
| prompt | string | required | Text description of the image to generate. | |
| n | integer | optional | Number of images to generate. Range depends on the model. | |
| size | string | optional | Output dimensions or aspect ratio, e.g. `1024x1024` or `16:9` (model-dependent). | |
| quality | string | optional | Quality tier, e.g. `standard`, `hd`, or model tiers like `1k`/`2k`/`4k`. | |
| response_format | string | optional | How 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.