Image API

Generate and edit images

Run GPT Image 2, GPT Image 2.5 Flare, GPT Image 2.5 Sunburst, Nano Banana, Nano Banana 2, Nano Banana 2 Lite, Nano Banana 2.1, Nano Banana Pro, Seedream 4.0, Seedream 4.5, Seedream 5.0, Seedream 5 Pro with one request format.

Endpoints

Use /v1/images/generations to create images from a prompt. It accepts JSON.

POSThttps://api.mlmux.com/v1/images/generations

Use /v1/images/edits to edit or combine images. Send image URLs in JSON, or upload files with multipart fields image and mask. Up to 16 images of 50 MB each are accepted.

POSThttps://api.mlmux.com/v1/images/edits

Request example

curl https://api.mlmux.com/v1/images/generations \
  -H "Authorization: Bearer $MLMUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "nano-banana-2",
  "prompt": "Editorial product photo of a ceramic mug on linen, soft window light",
  "aspect_ratio": "4:3",
  "resolution": "2K",
  "output_format": "png",
  "route_mode": "official-cheap"
}'

Requests are synchronous by default and return the images in the response. Add "async": true to get a task instead.

Parameters

Field	Type	Required	Description
`model`	string	Yes	A model ID from the table below. The provider prefix can be omitted when the short name is unique, for example `gpt-image-2`.
`prompt`	string	Yes	What to generate or change, up to 20,000 characters.
`image_urls`edits only	string[]	Yes	Public http(s) URLs of the input images, in order. `image_url` is also accepted for a single image.
`mask_url`edits only	string	No	URL of a mask image for models that support masked edits.
`route_mode`	string	No	`official` or `official-cheap`. Defaults to the key's route mode, then `official-cheap`.
`resolution`	string	No	`1K`, `2K`, or `4K` on Gemini models that support it. Nano Banana and Nano Banana 2 Lite have no resolution setting.
`size`	string	No	Output size for GPT Image and Seedream, such as `1024x1024`, `2K`, or `auto`.
`aspect_ratio`	string	No	Such as `1:1`, `16:9`, or `match_input_image`. Allowed values depend on the model.
`output_format`	string	No	`png`, `jpg`, `jpeg`, or `webp`, if the model supports it.
`n`	integer	No	Number of images, 1 to 4. Defaults to 1.
`async`	boolean	No	`true` returns a task (HTTP 202) to poll instead of waiting for the images.

Model IDs

Use these values in model. GET /v1/models returns the IDs available to your account.

Model	Model ID
GPT Image 2	`openai/gpt-image-2`
GPT Image 2.5 Flare	`weavy/gpt-image-2.5-flare`
GPT Image 2.5 Sunburst	`weavy/gpt-image-2.5-sunburst`
Nano Banana	`nano-banana`
Nano Banana 2	`nano-banana-2`
Nano Banana 2 Lite	`nano-banana-2-lite`
Nano Banana 2.1	`google/gemini-nano-banana-2.1`
Nano Banana Pro	`nano-banana-pro`
Seedream 4.0	`weavy/doubao-seedream-4-0-250828`
Seedream 4.5	`weavy/doubao-seedream-4-5-251128`
Seedream 5.0	`weavy/doubao-seedream-5-0-260128`
Seedream 5 Pro	`weavy/doubao-seedream-5-0-pro-260628`

GPT Image 2, GPT Image 2.5 Flare, and GPT Image 2.5 Sunburst currently run only on official. Send "route_mode": "official" with these models; without it, the request uses the default official-cheap and fails.

Response

A synchronous request returns HTTP 200 with one URL per image in data and the token counts in usage. Output URLs are hosted by MLMux; download the files you want to keep.

200 OK

{
  "created": 1767225600,
  "data": [
    { "url": "https://.../generated/9f2c....png" }
  ],
  "usage": {
    "input_tokens": 18,
    "output_tokens": 1120,
    "total_tokens": 1138,
    "input_tokens_details": { "text_tokens": 18, "image_tokens": 0 }
  }
}

Async requests

With "async": true, the request returns HTTP 202 and a task. Poll its poll_url until status is succeeded; the images are then listed in data.

GEThttps://api.mlmux.com/v1/images/generations/{task_id}

202 Accepted

{
  "id": "task_7c1e...",
  "object": "image.generation.task",
  "status": "queued",
  "created": 1767225600,
  "model": "nano-banana-2",
  "api_method": "images.generations.create",
  "poll_url": "/v1/images/generations/task_7c1e...",
  "progress": 0,
  "message": "queued",
  "estimated_charge_credits": 0.067
}

Succeeded

{
  "id": "task_7c1e...",
  "object": "image.generation.task",
  "status": "succeeded",
  "progress": 100,
  "message": "completed",
  "estimated_charge_credits": 0.067,
  "data": [
    { "url": "https://.../generated/7c1e....png" }
  ]
}

Image edit tasks are polled at /v1/images/edits/{task_id}. GET /v1/tasks/{task_id} works for any task.