Images & media

RouteMux exposes image generation and editing on the same OpenAI-compatible base URL you already use for chat. Pass an image-capable model slug, and the request is billed per the real number of images returned.

Find image-capable models by filtering the catalog:

curl "https://api.routemux.com/v1/models?capability=image_generation" \
  -H "Authorization: Bearer $ROUTEMUX_API_KEY"

Generate an image

curl https://api.routemux.com/v1/images/generations \
  -H "Authorization: Bearer $ROUTEMUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2.5-flare",
    "prompt": "A paper map of the world folded into a single hop",
    "n": 1
  }'

2K / 4K (gpt-image-2.5-sunburst / flare)

openai/gpt-image-2.5-sunburst and openai/gpt-image-2.5-flare both support real 2K and 4K output, with the same tiers, prices and limits, for both text-to-image (/v1/images/generations) and image-to-image (/v1/images/edits). The call is unchanged: the response is still synchronous and the body is still {created, data:[{b64_json}]} (base64 PNG). The tier is chosen by size:

Pricing is a flat amount per image, not per token. Limits for 2K / 4K:

• n must be 1.
• mask is not supported.
• Image-to-image accepts up to 10 reference images: files as multipart image / image[], or https URLs / data URLs as JSON image / images (images:[{image_url}] is also accepted).
• One image takes about 40 seconds to 4 minutes, longer at peak times, so do not keep a 30-, 60- or 120-second default read timeout on your client; allow at least 5 minutes.
• A size that is not listed in the table returns 400 and is not charged.
• For flare, image-to-image at the 2K tier measured 2048×1152 (16:9); text-to-image matches the table.
• To avoid charging twice for the same image, once a 2K / 4K request has started generating, the gateway does not resend it if it fails; whether to resend is up to you.

Text-to-image (2K, 16:9):

curl https://api.routemux.com/v1/images/generations \
  -H "Authorization: Bearer $ROUTEMUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2.5-sunburst",
    "prompt": "A product poster of a ceramic coffee cup on a linen tablecloth, soft morning light",
    "size": "2560x1440",
    "n": 1
  }' | jq -r '.data[0].b64_json' | base64 --decode > poster-2k.png

Image-to-image (4K, 16:9, two reference images uploaded as multipart):

curl https://api.routemux.com/v1/images/edits \
  -H "Authorization: Bearer $ROUTEMUX_API_KEY" \
  -F model=openai/gpt-image-2.5-sunburst \
  -F prompt="Place the logo on the cup and keep everything else unchanged" \
  -F size=3840x2160 \
  -F "image[][email protected]" \
  -F "image[][email protected]" \
  | jq -r '.data[0].b64_json' | base64 --decode > cup-4k.png

Parameters vs. OpenAI

This table covers only openai/gpt-image-2.5-sunburst, openai/gpt-image-2.5-flare and openai/gpt-image-2. Parameters marked "Not supported" have no effect even if you send them, so do not rely on them; "—" means this page makes no promise.

Nano Banana 2.1 (Gemini image)

google/gemini-nano-banana-2.1 (generally available from Google since 2026-10-06) uses the same OpenAI-compatible endpoints as above: text-to-image on /v1/images/generations, image editing on /v1/images/edits, with a synchronous {created, data:[{b64_json}]} response. size picks the tier, and aspect_ratio can set the frame directly:

• aspect_ratio (optional): auto, 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 set, it wins; otherwise the closest ratio to size is used, and literal tiers ("2K" / "4K") let the model choose. Any other value returns 400 and is not charged.
• output_format: PNG by default; pass jpeg for JPEG (a 4K PNG is about 20 MB, so JPEG is the better choice when size matters).
• n must be 1; mask is not supported; editing accepts up to 10 reference images, passed the same way as above.
• Each image takes about 25–50 seconds.
• Synchronous only: async jobs (/v1/jobs) do not accept this model.
• Available after your account's first top-up.

curl https://api.routemux.com/v1/images/generations \
  -H "Authorization: Bearer $ROUTEMUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-nano-banana-2.1",
    "prompt": "An infographic about the water cycle with clear English labels",
    "size": "2K",
    "aspect_ratio": "4:5"
  }' | jq -r '.data[0].b64_json' | base64 --decode > water-cycle-2k.png

Nano Banana Pro (Gemini 3 Pro Image)

google/gemini-3-pro-image is the Pro model in Google's image family. You can call it as google/gemini-3-pro-image, gemini-3-pro-image or gemini-nano-banana-pro. It works like Nano Banana 2.1 (same endpoints, size tiers, aspect_ratio and output_format):

How it differs from Nano Banana 2.1:

• aspect_ratio has 10 values: auto, 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 (no 1:4, 4:1, 1:8, 8:1). Any other value returns 400 and is not charged.
• Image-to-image accepts up to 8 reference images.
• At 4K the image comes back as JPEG even when you ask for PNG.
• One image takes about 30–60 seconds.
• The Gemini-native image endpoint (generateContent) is no longer offered; use the OpenAI-compatible endpoints above.

The older Gemini image models Gemini 2.5 Flash Image and 3.1 Flash Image were retired on 2026-10-18 and return 410; use Nano Banana 2.1 instead.

Long-running and async jobs

Image and video generation can take longer than a synchronous HTTP request should hold open. When enabled, the async jobs surface lets you submit work and poll for the result:

POST   /v1/jobs        # kind: "image_generation" | "video_generation"
GET    /v1/jobs/:id
GET    /v1/jobs
DELETE /v1/jobs/:id     # cancel a queued job

Async jobs still authenticate with your API key, hold wallet credit, and settle usage through the same billing path as synchronous requests — there is no separate billing channel. Job status moves through queued, running, completed, failed, cancelled, and expired. Pass X-Idempotency-Key so a retried submission returns the existing job instead of creating a duplicate.

See Video generation for the video-specific modes.