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