> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixroute.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Image Generation

> Generate and edit images with the MixRoute Images API

## Introduction

The image generation endpoint generates images through `POST /v1/images/generations` and supports workflows such as text-to-image, image-to-image, and image editing. This endpoint uses an OpenAI Images API-compatible format. The main examples currently use `gpt-image-2`, which has been verified successfully.

<Warning>
  Use the full model IDs returned by `GET /v1/models`. Do not use legacy aliases or shortened names.
</Warning>

<Tip>
  Gemini image models use the native Gemini endpoint `POST /v1/models/{model}:generateContent`; they do not use `POST /v1/images/generations`.
</Tip>

## API Base URL

```text theme={null}
https://api.mixroute.ai/v1
```

## Authentication

Use a Bearer Token:

```http theme={null}
Authorization: Bearer sk-xxxxxxxxxx
```

## Request Body

<ParamField body="model" type="string" required>
  The image model ID to call. We recommend calling `GET /v1/models` when your application starts to retrieve the current list of available models.
</ParamField>

<ParamField body="prompt" type="string">
  The prompt for text-to-image or image editing.
</ParamField>

<ParamField body="size" type="string">
  Output image size. Common values include `1024x1024`, `1024x1536`, and `1536x1024`. Some models support higher resolutions or size values in different formats.
</ParamField>

<ParamField body="quality" type="string">
  Image quality. Common values for the GPT Image series are `"low"`, `"medium"`, and `"high"`.
</ParamField>

<ParamField body="n" type="integer">
  Number of images to generate. The GPT Image series supports `1-10`.
</ParamField>

<ParamField body="response_format" type="string">
  Response format. Pass this only when the selected model explicitly supports it, such as `"url"` or `"b64_json"`. `gpt-image-2` currently does not accept this parameter, so omit it when calling that model.
</ParamField>

<ParamField body="image" type="string">
  A single input image, as an image URL or Base64/Data URL. Use this for image-to-image or editing workflows.
</ParamField>

<ParamField body="images" type="array">
  An array of input images. Use this for multi-image fusion or multi-reference image editing.
</ParamField>

<ParamField body="input_fidelity" type="string">
  Input fidelity. GPT Image image-to-image workflows can use `"auto"`, `"high"`, `"medium"`, or `"low"`.
</ParamField>

<ParamField body="input" type="object">
  The native input object for Qwen image models. The common structure is `input.messages[].content[]`, where content can include `text` or `image`.
</ParamField>

<ParamField body="parameters" type="object">
  The parameter object for Qwen image models, such as `size`, `seed`, `watermark`, `negative_prompt`, `prompt_extend`, and `n`.
</ParamField>

<ParamField body="contents" type="array">
  Image context input for the Seedream series. Content can include image URLs, Data URLs, or text parts. Exact capabilities depend on the model version and account routing channel.
</ParamField>

***

## Basic Examples

<Tabs>
  <Tab title="GPT Image">
    <Tabs>
      <Tab title="Text-to-image">
        ```bash theme={null}
        curl -X POST "https://api.mixroute.ai/v1/images/generations" \
          -H "Authorization: Bearer sk-xxxxxxxxxx" \
          -H "Content-Type: application/json" \
          -d '{
            "model": "gpt-image-2",
            "prompt": "A cute orange kitten sitting in a garden, bright sunshine, high-quality photography",
            "size": "1024x1024",
            "quality": "low",
            "n": 1
          }'
        ```
      </Tab>

      <Tab title="Image-to-image">
        ```bash theme={null}
        curl -X POST "https://api.mixroute.ai/v1/images/generations" \
          -H "Authorization: Bearer sk-xxxxxxxxxx" \
          -H "Content-Type: application/json" \
          -d '{
            "model": "gpt-image-2",
            "prompt": "Turn this image into an oil painting",
            "size": "1024x1024",
            "quality": "low",
            "input_fidelity": "medium",
            "n": 1,
            "image": "data:image/png;base64,iVBORw0KGgoAAxxxx..."
          }'
        ```
      </Tab>

      <Tab title="Multi-image fusion">
        ```bash theme={null}
        curl -X POST "https://api.mixroute.ai/v1/images/generations" \
          -H "Authorization: Bearer sk-xxxxxxxxxx" \
          -H "Content-Type: application/json" \
          -d '{
            "model": "gpt-image-2",
            "prompt": "Apply the style of the first image to the content of the second image",
            "size": "1024x1024",
            "quality": "low",
            "input_fidelity": "high",
            "n": 1,
            "images": [
              "data:image/png;base64,iVBORw0KGgoAAxxxx...",
              "data:image/png;base64,iVBORw0KGgoAAyyyy..."
            ]
          }'
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

***

## Model-Specific Parameters

### GPT Image

<ParamField body="size" type="string">
  Image size. Supports `1024x1024`, `1024x1536`, and `1536x1024`.
</ParamField>

<ParamField body="quality" type="string">
  Image quality: `"low"`, `"medium"`, or `"high"`.
</ParamField>

<ParamField body="n" type="integer">
  Number of images to generate, from `1-10`.
</ParamField>

<ParamField body="input_fidelity" type="string">
  Input fidelity, used only in image-to-image or editing mode: `"auto"`, `"high"`, `"medium"`, or `"low"`.
</ParamField>

### Qwen

<ParamField body="input" type="object">
  Native message object. Pass `text` for text-to-image. For image editing, pass both `image` and `text`.
</ParamField>

<ParamField body="parameters" type="object">
  Generation parameter object:

  * `size`: image size, such as `"1024*1024"`
  * `seed`: random seed, from `0-2147483647`
  * `watermark`: whether to add a watermark
  * `prompt_extend`: whether to enable prompt expansion
  * `negative_prompt`: negative prompt
  * `n`: number of output images
</ParamField>

### Seedream

<ParamField body="size" type="string">
  Image size. Seedream 4.x/5.x commonly uses 2K/4K sizes such as `2048x2048`, `2304x1728`, `1728x2304`, `2560x1440`, and `1440x2560`.
</ParamField>

<ParamField body="watermark" type="boolean">
  Whether to add a watermark.
</ParamField>

<ParamField body="seed" type="integer">
  Random seed for controlling generation randomness. The value range is `0-2147483647`.
</ParamField>

<ParamField body="contents" type="array">
  Image context input. Seedream 4.x/5.x usually supports single-image or multi-image input; actual availability depends on the model version and account routing channel.
</ParamField>

<ParamField body="sequential_image_generation" type="string">
  Group image generation switch: `"disabled"` or `"auto"`.
</ParamField>

<ParamField body="optimize_prompt_options" type="object">
  Prompt optimization options, such as `{"mode": "standard"}` or `{"mode": "fast"}`.
</ParamField>

***

## Supported Models

The following models come from the current image-related model list returned by `GET /v1/models`.

### GPT Image Series

| Model ID        | Core Capabilities                                                    | Notes                                                                     |
| --------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `gpt-image-2`   | Text-to-image, image-to-image, multi-image fusion, quality selection | Recommended for new projects; verified with `POST /v1/images/generations` |
| `gpt-image-1.5` | Text-to-image, image-to-image, multi-image fusion                    | Verified with `POST /v1/images/generations`                               |
| `gpt-image-1`   | Text-to-image, image-to-image, multi-image fusion                    | Verified with `POST /v1/images/generations`                               |

### Qwen Series

| Model ID               | Core Capabilities                                                                |
| ---------------------- | -------------------------------------------------------------------------------- |
| `qwen-image-2.0-pro`   | High-quality text-to-image, Chinese and English text rendering, prompt expansion |
| `qwen-image-2.0`       | Text-to-image, Chinese and English text rendering                                |
| `qwen-image-max`       | High-quality text-to-image                                                       |
| `qwen-image-plus`      | Text-to-image, Chinese and English text rendering, prompt expansion              |
| `qwen-image`           | Text-to-image                                                                    |
| `qwen-image-edit-max`  | High-quality image editing, style transfer, object addition and removal          |
| `qwen-image-edit-plus` | Image editing, style transfer, object addition and removal                       |
| `qwen-image-edit`      | Image editing                                                                    |

### Seedream Series

| Model ID                   | Core Capabilities                                                                              |
| -------------------------- | ---------------------------------------------------------------------------------------------- |
| `seedream-5-0-260128`      | Text-to-image, image-to-image, multi-image fusion, high-resolution output                      |
| `seedream-5-0-lite-260128` | Lower-cost text-to-image and image-to-image                                                    |
| `seedream-4-5-251128`      | Text-to-image, image-to-image, multi-image fusion, group image generation, prompt optimization |
| `seedream-4-0-250828`      | Text-to-image, image-to-image, multi-image fusion, group image generation, 2K/4K output        |

### Gemini Image Series

| Model ID                         | How to Call                                   |
| -------------------------------- | --------------------------------------------- |
| `gemini-3.1-flash-image`         | Use `POST /v1/models/{model}:generateContent` |
| `gemini-3.1-flash-image-preview` | Use `POST /v1/models/{model}:generateContent` |
| `gemini-3-pro-image`             | Use `POST /v1/models/{model}:generateContent` |
| `gemini-3-pro-image-preview`     | Use `POST /v1/models/{model}:generateContent` |
| `gemini-2.5-flash-image`         | Use `POST /v1/models/{model}:generateContent` |

***

## Best Practices

### Model Selection

* Prefer `gpt-image-2` as the general-purpose model for `/v1/images/generations` in new projects.
* When you need Chinese and English text rendering, test `qwen-image-2.0-pro` first.
* When you need image editing, test `gpt-image-2` or `qwen-image-edit-max` first.
* When you need Gemini/Nano Banana image capabilities, use the native Gemini image endpoint instead of the Images API endpoint.

### Prompt Suggestions

* Clearly specify the subject, style, lighting, composition, and intended output use.
* When you need text rendering, put the text to render in quotation marks.
* For image-to-image, explain which elements should be preserved and which should be changed.
* For multi-image fusion, clearly define each reference image's role, such as "use the first image as the style reference and the second image as the subject content."

***

## FAQ

<AccordionGroup>
  <Accordion title="Why can't I keep using legacy aliases?">
    The current model list is based on the full model IDs returned by `GET /v1/models`. Legacy aliases or shortened names may fail to route to an available channel.
  </Accordion>

  <Accordion title="Why aren't Gemini image models in the Images API examples?">
    Gemini image models currently use the native Gemini endpoint: `POST /v1/models/{model}:generateContent`. `POST /v1/images/generations` is not the right primary call path for Gemini image models.
  </Accordion>

  <Accordion title="Can I generate multiple images at the same time?">
    The GPT Image series uses the `n` parameter to control the number of generated images. Whether Qwen and Seedream support multiple outputs depends on the model and account routing channel.
  </Accordion>

  <Accordion title="Will the response return a URL or Base64?">
    It depends on the model and parameters. The GPT Image series usually returns `b64_json`, and `gpt-image-2` currently does not accept the `response_format` parameter. Qwen and Seedream response formats depend on the model implementation and account routing channel.
  </Accordion>
</AccordionGroup>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.mixroute.ai/v1/images/generations \
    --header 'Authorization: Bearer sk-xxxxxxxxxx' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "gpt-image-2",
      "prompt": "A cute orange kitten sitting in a garden",
      "size": "1024x1024",
      "quality": "low",
      "n": 1
    }'
  ```

  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      api_key="sk-xxxxxxxxxx",
      base_url="https://api.mixroute.ai/v1"
  )

  response = client.images.generate(
      model="gpt-image-2",
      prompt="A cute orange kitten sitting in a garden",
      size="1024x1024",
      quality="low",
      n=1
  )
  print(response.data[0].b64_json)
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.mixroute.ai/v1/images/generations', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk-xxxxxxxxxx',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'gpt-image-2',
      prompt: 'A cute orange kitten sitting in a garden',
      size: '1024x1024',
      quality: 'low',
      n: 1
    })
  });
  const data = await response.json();
  console.log(data.data[0].b64_json);
  ```

  ```php PHP theme={null}
  <?php
  $client = new GuzzleHttp\Client();
  $response = $client->post('https://api.mixroute.ai/v1/images/generations', [
      'headers' => [
          'Authorization' => 'Bearer sk-xxxxxxxxxx',
          'Content-Type' => 'application/json',
      ],
      'json' => [
          'model' => 'gpt-image-2',
          'prompt' => 'A cute orange kitten sitting in a garden',
          'size' => '1024x1024',
          'quality' => 'low',
          'n' => 1
      ]
  ]);
  echo $response->getBody();
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "net/http"
  )

  func main() {
      payload := map[string]interface{}{
          "model": "gpt-image-2",
          "prompt": "A cute orange kitten sitting in a garden",
          "size": "1024x1024",
          "quality": "low",
          "n": 1,
      }
      body, _ := json.Marshal(payload)
      req, _ := http.NewRequest("POST", "https://api.mixroute.ai/v1/images/generations", bytes.NewBuffer(body))
      req.Header.Set("Authorization", "Bearer sk-xxxxxxxxxx")
      req.Header.Set("Content-Type", "application/json")
      http.DefaultClient.Do(req)
  }
  ```

  ```java Java theme={null}
  import java.net.http.*;
  import java.net.URI;

  HttpClient client = HttpClient.newHttpClient();
  String json = """
      {
          "model": "gpt-image-2",
          "prompt": "A cute orange kitten sitting in a garden",
          "size": "1024x1024",
          "quality": "low",
          "n": 1
      }
      """;
  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.mixroute.ai/v1/images/generations"))
      .header("Authorization", "Bearer sk-xxxxxxxxxx")
      .header("Content-Type", "application/json")
      .POST(HttpRequest.BodyPublishers.ofString(json))
      .build();
  HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
  System.out.println(response.body());
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'json'

  uri = URI('https://api.mixroute.ai/v1/images/generations')
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(uri)
  request['Authorization'] = 'Bearer sk-xxxxxxxxxx'
  request['Content-Type'] = 'application/json'
  request.body = {
    model: 'gpt-image-2',
    prompt: 'A cute orange kitten sitting in a garden',
    size: '1024x1024',
    quality: 'low',
    n: 1
  }.to_json

  response = http.request(request)
  puts response.body
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "created": 1790480000,
    "data": [
      {
        "b64_json": "iVBORw0KGgoAAAANSUhEUgAABAAAAAQA..."
      }
    ]
  }
  ```
</ResponseExample>