> ## 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.

# 圖片生成

> 使用 MixRoute Images API 生成和編輯圖片

## 簡介

圖片生成介面用於透過 `POST /v1/images/generations` 生成圖片，支援文字生圖、圖生圖和圖片編輯等工作流程。此端點採用 OpenAI Images API 相容格式，目前主要範例使用已驗證成功的 `gpt-image-2`。

<Warning>
  請使用 `GET /v1/models` 回傳的完整模型 ID，不要使用舊別名或簡寫名稱。
</Warning>

<Tip>
  Gemini 圖片模型使用原生 Gemini 端點 `POST /v1/models/{model}:generateContent`，不使用 `POST /v1/images/generations`。
</Tip>

## API Base URL

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

## 認證

使用 Bearer Token：

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

## 請求體結構

<ParamField body="model" type="string" required>
  要呼叫的圖片模型 ID。建議在應用程式啟動時呼叫 `GET /v1/models` 取得目前可用的模型列表。
</ParamField>

<ParamField body="prompt" type="string">
  文字生圖或圖片編輯的提示詞。
</ParamField>

<ParamField body="size" type="string">
  輸出圖片尺寸。常用值包括 `1024x1024`、`1024x1536`、`1536x1024`。部分模型支援更高解析度或不同格式的尺寸值。
</ParamField>

<ParamField body="quality" type="string">
  圖片品質。GPT Image 系列常用值為 `"low"`、`"medium"`、`"high"`。
</ParamField>

<ParamField body="n" type="integer">
  生成圖片數量。GPT Image 系列支援 `1-10`。
</ParamField>

<ParamField body="response_format" type="string">
  回應格式。僅在所選模型明確支援時傳入，例如 `"url"` 或 `"b64_json"`。`gpt-image-2` 目前不接受此參數，呼叫時請省略。
</ParamField>

<ParamField body="image" type="string">
  單張輸入圖片，支援圖片 URL 或 Base64/Data URL。用於圖生圖或編輯工作流程。
</ParamField>

<ParamField body="images" type="array">
  多張輸入圖片陣列。用於多圖融合或多參考圖編輯。
</ParamField>

<ParamField body="input_fidelity" type="string">
  輸入保真度。GPT Image 圖生圖場景可使用 `"auto"`、`"high"`、`"medium"`、`"low"`。
</ParamField>

<ParamField body="input" type="object">
  通義千問圖片模型的原生輸入物件。常見結構為 `input.messages[].content[]`，內容可以包含 `text` 或 `image`。
</ParamField>

<ParamField body="parameters" type="object">
  通義千問圖片模型的參數物件，例如 `size`、`seed`、`watermark`、`negative_prompt`、`prompt_extend` 和 `n`。
</ParamField>

<ParamField body="contents" type="array">
  Seedream 系列的圖片上下文輸入。內容可以包含圖片 URL、Data URL 或文字片段，具體能力取決於模型版本和帳號管道。
</ParamField>

***

## 基礎範例

<Tabs>
  <Tab title="GPT Image">
    <Tabs>
      <Tab title="文字生圖">
        ```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": "一隻可愛的橘色小貓坐在花園裡，陽光明媚，高品質攝影",
            "size": "1024x1024",
            "quality": "low",
            "n": 1
          }'
        ```
      </Tab>

      <Tab title="圖生圖">
        ```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": "將這張圖片改成油畫風格",
            "size": "1024x1024",
            "quality": "low",
            "input_fidelity": "medium",
            "n": 1,
            "image": "data:image/png;base64,iVBORw0KGgoAAxxxx..."
          }'
        ```
      </Tab>

      <Tab title="多圖融合">
        ```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": "將第一張圖的風格套用到第二張圖的內容上",
            "size": "1024x1024",
            "quality": "low",
            "input_fidelity": "high",
            "n": 1,
            "images": [
              "data:image/png;base64,iVBORw0KGgoAAxxxx...",
              "data:image/png;base64,iVBORw0KGgoAAyyyy..."
            ]
          }'
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

***

## 模型專用參數

### GPT Image

<ParamField body="size" type="string">
  圖片尺寸，支援 `1024x1024`、`1024x1536`、`1536x1024`。
</ParamField>

<ParamField body="quality" type="string">
  圖片品質：`"low"`、`"medium"`、`"high"`。
</ParamField>

<ParamField body="n" type="integer">
  生成圖片數量，範圍 `1-10`。
</ParamField>

<ParamField body="input_fidelity" type="string">
  輸入保真度，僅在圖生圖或編輯模式下使用：`"auto"`、`"high"`、`"medium"`、`"low"`。
</ParamField>

### 通義千問

<ParamField body="input" type="object">
  原生訊息物件。文字生圖傳入 `text`，圖片編輯同時傳入 `image` 和 `text`。
</ParamField>

<ParamField body="parameters" type="object">
  生成參數物件：

  * `size`: 圖片尺寸，例如 `"1024*1024"`
  * `seed`: 隨機種子，範圍 `0-2147483647`
  * `watermark`: 是否加入浮水印
  * `prompt_extend`: 是否啟用提示詞擴展
  * `negative_prompt`: 負面提示詞
  * `n`: 輸出圖片數量
</ParamField>

### Seedream

<ParamField body="size" type="string">
  圖片尺寸。Seedream 4.x/5.x 常用 `2048x2048`、`2304x1728`、`1728x2304`、`2560x1440`、`1440x2560` 等 2K/4K 尺寸。
</ParamField>

<ParamField body="watermark" type="boolean">
  是否加入浮水印。
</ParamField>

<ParamField body="seed" type="integer">
  隨機種子，用於控制生成結果的隨機性。取值範圍為 `0-2147483647`。
</ParamField>

<ParamField body="contents" type="array">
  圖片上下文輸入。Seedream 4.x/5.x 通常支援單圖或多圖輸入；實際可用性取決於模型版本和帳號管道。
</ParamField>

<ParamField body="sequential_image_generation" type="string">
  組圖功能開關：`"disabled"` 或 `"auto"`。
</ParamField>

<ParamField body="optimize_prompt_options" type="object">
  提示詞最佳化選項，例如 `{"mode": "standard"}` 或 `{"mode": "fast"}`。
</ParamField>

***

## 支援的模型

以下模型來自 `GET /v1/models` 目前回傳的圖片相關模型清單。

### GPT Image 系列

| 模型 ID           | 核心能力               | 備註                                           |
| --------------- | ------------------ | -------------------------------------------- |
| `gpt-image-2`   | 文字生圖、圖生圖、多圖融合、品質選擇 | 建議新專案使用；已通過 `POST /v1/images/generations` 驗證 |
| `gpt-image-1.5` | 文字生圖、圖生圖、多圖融合      | 已通過 `POST /v1/images/generations` 驗證         |
| `gpt-image-1`   | 文字生圖、圖生圖、多圖融合      | 已通過 `POST /v1/images/generations` 驗證         |

### 通義千問系列

| 模型 ID                  | 核心能力                  |
| ---------------------- | --------------------- |
| `qwen-image-2.0-pro`   | 高品質文字生圖、中英文文字渲染、提示詞擴展 |
| `qwen-image-2.0`       | 文字生圖、中英文文字渲染          |
| `qwen-image-max`       | 高品質文字生圖               |
| `qwen-image-plus`      | 文字生圖、中英文文字渲染、提示詞擴展    |
| `qwen-image`           | 文字生圖                  |
| `qwen-image-edit-max`  | 高品質圖片編輯、風格遷移、物件增刪     |
| `qwen-image-edit-plus` | 圖片編輯、風格遷移、物件增刪        |
| `qwen-image-edit`      | 圖片編輯                  |

### Seedream 系列

| 模型 ID                      | 核心能力                        |
| -------------------------- | --------------------------- |
| `seedream-5-0-260128`      | 文字生圖、圖生圖、多圖融合、高解析度輸出        |
| `seedream-5-0-lite-260128` | 低成本文字生圖、圖生圖                 |
| `seedream-4-5-251128`      | 文字生圖、圖生圖、多圖融合、組圖功能、提示詞最佳化   |
| `seedream-4-0-250828`      | 文字生圖、圖生圖、多圖融合、組圖功能、2K/4K 輸出 |

### Gemini 圖片系列

| 模型 ID                            | 呼叫方式                                         |
| -------------------------------- | -------------------------------------------- |
| `gemini-3.1-flash-image`         | 使用 `POST /v1/models/{model}:generateContent` |
| `gemini-3.1-flash-image-preview` | 使用 `POST /v1/models/{model}:generateContent` |
| `gemini-3-pro-image`             | 使用 `POST /v1/models/{model}:generateContent` |
| `gemini-3-pro-image-preview`     | 使用 `POST /v1/models/{model}:generateContent` |
| `gemini-2.5-flash-image`         | 使用 `POST /v1/models/{model}:generateContent` |

***

## 最佳實務

### 模型選擇

* 新專案優先使用 `gpt-image-2` 作為 `/v1/images/generations` 的通用模型。
* 需要中英文文字渲染時，優先測試 `qwen-image-2.0-pro`。
* 需要圖片編輯時，優先測試 `gpt-image-2` 或 `qwen-image-edit-max`。
* 需要 Gemini/Nano Banana 圖片能力時，請使用 Gemini 原生圖片端點，而不是 Images API 端點。

### 提示詞建議

* 明確畫面主體、風格、光線、構圖和輸出用途。
* 需要文字渲染時，將要渲染的文字放在引號中。
* 圖生圖時說明需要保留哪些元素、修改哪些元素。
* 多圖融合時明確每張參考圖的角色，例如「第一張作為風格參考，第二張作為主體內容」。

***

## 常見問題

<AccordionGroup>
  <Accordion title="為什麼不能繼續使用舊別名？">
    目前模型清單以 `GET /v1/models` 回傳的完整模型 ID 為準。舊別名或簡寫名稱可能無法路由到可用管道。
  </Accordion>

  <Accordion title="為什麼 Gemini 圖片模型不在 Images API 範例中？">
    目前 Gemini 圖片模型透過原生 Gemini 端點呼叫：`POST /v1/models/{model}:generateContent`。`POST /v1/images/generations` 不適合作為 Gemini 圖片模型的主要呼叫路徑。
  </Accordion>

  <Accordion title="可以同時生成多張圖片嗎？">
    GPT Image 系列使用 `n` 參數控制生成數量。通義千問和 Seedream 是否支援多張輸出，取決於模型和帳號管道。
  </Accordion>

  <Accordion title="回傳 URL 還是 Base64？">
    取決於模型和參數。GPT Image 系列通常回傳 `b64_json`，且 `gpt-image-2` 目前不接受 `response_format` 參數；通義千問和 Seedream 的回傳格式取決於模型實作和帳號管道。
  </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": "一隻可愛的橘色小貓坐在花園裡",
      "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="一隻可愛的橘色小貓坐在花園裡",
      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: '一隻可愛的橘色小貓坐在花園裡',
      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' => '一隻可愛的橘色小貓坐在花園裡',
          '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": "一隻可愛的橘色小貓坐在花園裡",
          "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": "一隻可愛的橘色小貓坐在花園裡",
          "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: '一隻可愛的橘色小貓坐在花園裡',
    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>