Skip to main content
POST
/
images
Generate an image
curl --request POST \
  --url https://openrouter.ai/api/v1/images \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "bytedance-seed/seedream-4.5",
  "prompt": "a red panda astronaut floating in space, studio lighting"
}
'
{
  "created": 1748372400,
  "data": [
    {
      "b64_json": "<base64-encoded-image>"
    }
  ],
  "usage": {
    "completion_tokens": 4175,
    "cost": 0.04,
    "prompt_tokens": 0,
    "total_tokens": 4175
  }
}

Authorizations

​
Authorization
string
header
required

API key as bearer token in Authorization header

Body

application/json

Image generation request input

​
model
string
required

The image generation model to use

Example:

"bytedance-seed/seedream-4.5"

​
prompt
string
required

Text description of the desired image

Minimum string length: 1
Example:

"a red panda astronaut floating in space, studio lighting"

​
aspect_ratio
enum<string>

Normalized aspect ratio of the generated image. Providers clamp to their supported subset.

Available options:
1:1,
1:2,
1:4,
1:8,
2:1,
2:3,
3:2,
3:4,
4:1,
4:3,
4:5,
5:4,
8:1,
9:16,
16:9,
9:19.5,
19.5:9,
9:20,
20:9,
9:21,
21:9,
auto
Example:

"16:9"

​
background
enum<string>

Background treatment. transparent requires an output_format that supports alpha (png or webp).

Available options:
auto,
transparent,
opaque
Example:

"auto"

​
input_references
object[]

Reference images to guide image-to-image generation, as base64 data URLs or HTTP(S) URLs.

Maximum array length: 16
​
n
integer

Number of images to generate (1-10). Providers that only support single-image generation reject n > 1.

Example:

1

​
output_compression
integer

Compression level (0-100) for webp/jpeg output. Ignored for png and by providers without a compression knob.

Example:

100

​
output_format
enum<string>

Encoding of the returned image bytes. Most models produce raster formats (png, jpeg, webp). SVG is supported by vectorization models (e.g. Quiver) — the SVG markup is UTF-8 base64-encoded in b64_json.

Available options:
png,
jpeg,
webp,
svg
Example:

"png"

​
provider
object

Provider-specific passthrough configuration

​
quality
enum<string>

Rendering quality. Providers without a quality knob ignore this.

Available options:
auto,
low,
medium,
high
Example:

"high"

​
resolution
enum<string>

Normalized resolution tier of the generated image. Concrete pixel dimensions are derived per-provider.

Available options:
512,
1K,
2K,
4K
Example:

"2K"

​
seed
integer

If specified, the generation will sample deterministically, such that repeated requests with the same seed and parameters should return the same result. Determinism is not guaranteed for all providers.

​
size
string

Optional. A convenience shorthand for output dimensions — pass a tier ("2K", "4K") or explicit pixels ("2048x2048") and we normalize it to the right dimensions for the chosen provider. Interchangeable with resolution + aspect_ratio; use those directly for enumerated, per-model discoverable values. Conflicting size + resolution/aspect_ratio is rejected.

Example:

"2K"

​
stream
boolean

If true, partial images are streamed as SSE events as they become available. Only supported by providers with native streaming (currently OpenAI). Non-streaming providers ignore this flag and return a buffered response.

Response

Image generation response

Image generation response

​
created
integer
required

Unix timestamp (seconds) when the image was generated

Example:

1748372400

​
data
object[]
required

Generated images

​
usage
object

Token and cost usage for the image generation request, when available

Example:
{
  "completion_tokens": 4175,
  "cost": 0.04,
  "prompt_tokens": 0,
  "total_tokens": 4175
}