Image Generation

Generate images with any model available on ImageRouter. Supports both Text-to-Image and Image-to-Image generation. Requests can be encoded as application/json or multipart/form-data (optimal for file uploads).

curl 'https://api.imagerouter.io/v1/openai/images/generations' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--json '{
  "prompt": "YOUR_PROMPT",
  "model": "test/test",
  "quality": "auto",
  "size": "auto",
  "response_format": "url",
  "output_format": "webp",
  "image": "https://example.com/your_image.jpg"
}'

const url = 'https://api.imagerouter.io/v1/openai/images/generations'

// Text-to-Image
const payload = {
  prompt: 'YOUR_PROMPT',
  model: 'test/test',
  quality: 'auto',
  size: 'auto',
  response_format: 'url',
  output_format: 'webp'
}

// Image-to-Image — pass a URL or data URI string
// payload.image = 'https://example.com/your_image.jpg'
// payload.image = ['https://example.com/img1.jpg', 'https://example.com/img2.jpg']

const response = await fetch(url, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
})

const data = await response.json()
console.log(data)

import requests

url = "https://api.imagerouter.io/v1/openai/images/generations"
headers = {
  "Authorization": "Bearer YOUR_API_KEY"
}

# Text-to-Image
payload = {
  "prompt": "YOUR_PROMPT",
  "model": "test/test",
  "quality": "auto",
  "size": "auto",
  "response_format": "url",
  "output_format": "webp"
}

# Image-to-Image — pass a URL or data URI string
# payload["image"] = "https://example.com/your_image.jpg"
# payload["image"] = ["https://example.com/img1.jpg", "https://example.com/img2.jpg"]

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Both JSON and Form-Data encoding are accepted by the API. JSON is compatible with OpenAI’s GPT Image, Form-Data is compatible with GPT Image (edit) schema.

Show Form-Data formatted example

curl 'https://api.imagerouter.io/v1/openai/images/edits' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-F 'prompt=YOUR_PROMPT' \
-F 'model=openai/gpt-image-1' \
-F 'quality=auto' \
-F 'size=auto' \
-F 'response_format=url' \
-F 'output_format=webp' \
-F 'image[]=@your_image1.webp' \
-F 'image[]=@your_image2.webp' \
-F 'mask[]=@your_mask.webp'

const formData = new FormData()
formData.append('prompt', 'YOUR_PROMPT')
formData.append('model', 'openai/gpt-image-1')
formData.append('quality', 'auto')
formData.append('size', 'auto')
formData.append('response_format', 'url')
formData.append('output_format', 'webp')

// Add your image files (up to 16)
const imageFile1 = await fetch('your_image1.webp').then(r => r.blob())
formData.append('image[]', imageFile1)

// or from local file
const imagePath = '/home/phoenics/projects/Image router/materials/logo.png'
const imageBuffer = fs.readFileSync(imagePath)
const imageBlob = new Blob([imageBuffer], { type: 'image/png' })
formData.append('image[]', imageBlob, path.basename(imagePath))

// Add mask file - some models support/require it
//const maskFile = await fetch('your_mask.webp').then(r => r.blob())
//formData.append('mask[]', maskFile)

const response = await fetch('https://api.imagerouter.io/v1/openai/images/edits', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: formData
})

const data = await response.json()
console.log(data)

import requests

url = "https://api.imagerouter.io/v1/openai/images/edits"
headers = {
  "Authorization": "Bearer YOUR_API_KEY"
}

payload = {
  "prompt": "YOUR_PROMPT",
  "model": "openai/gpt-image-1",
  "quality": "auto",
  "size": "auto",
  "response_format": "url",
  "output_format": "webp"
}

with open("your_image1.webp", "rb") as img1, \
  open("your_image2.webp", "rb") as img2, \
  open("your_mask.webp", "rb") as mask:
  files = {
      "image[]": [img1, img2],
      "mask[]": mask
  }
  response = requests.post(url, files=files, data=payload, headers=headers)
  print(response.json())

note: /v1/openai/images/generations and /v1/openai/images/edits are the exact same, available at 2 URLs for compatibility reasons.

Parameters

model required Image model to use for generation.
prompt optional Text input for generating images. Many models require prompt, but not all.
quality optional Models supporting this parameter have “quality” feature label here
- auto [default] - Usually points to “medium”, but some models (eg. gpt-image-1) automatically adjust quality based on your prompt.
- low
- medium
- high
size optional Accepted values are different for each model. Some models and providers completely ignore size.
- auto [default] - Uses the default recommended size for each model. Some models (eg. gpt-image-1) automatically adjust size based on your prompt.
- WIDTHxHEIGHT (eg 1024x1024)
response_format optional
- url [default] - Returns the image URL hosted on ImageRouter’s servers. The image is saved in your logs. and is publicly accessible with the URL if you share it.
- b64_json - Returns the image as base64-encoded JSON data. The image is saved in your logs. and is publicly accessible with the URL if you share it.
- b64_ephemeral - Same as b64_json but the image is not saved in our system. The provider may still have it.
output_format optional Image format for the generated output.
- webp [default]
- jpeg
- png
image / image[] optional Input image(s) for Image-to-Image generation. (Supported models have “edit” label here.) Accepted formats:
- File upload — multipart/form-data with image[] field(s) (up to 16 files)
- URL string — "https://example.com/photo.jpg" (passed as JSON string or form field)
- Data URI string — "data:image/png;base64,..." (passed as JSON string or form field)
URL and data URI strings can be sent either as a single string or an array of strings (up to 16). This is OpenAI-compatible.
mask / mask[] optional Image editing mask (most models don’t need this). Accepts the same formats as image: file upload, URL string, or data URI string.

Response

The OpenAI compatible response makes sure you can use ImageRouter anywhere GPT-Image is already implemented.

{
  "created": 1769286389027, // timestamp
  "data":[
    {
      "url": "https://storage.imagerouter.io/fffb4426-efbd-4bcc-87d5-47e6936bf0bb.webp"
      // or "b64_json": "...", if you select a different response_format
    }
  ],
  "latency": 6942,
  "cost": 0.004
}