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

# MAI-Image-2.6 图像生成

> 支持文生图、单图编辑、最多 5 张参考图合成及联网增强，提供高质量版与 Flash 版。

## 模型选择

| 模型 ID | 特点 |
| - | - |
| `mai-image-2.6` | 高质量版，适合注重画质的场景 |
| `mai-image-2.6-flash` | 快速版，画质略低，速度更快、成本更低 |

两个模型的能力和参数相同，均只支持每次生成 1 张图片。实际价格以[模型定价](https://apimart.ai/pricing)为准。

<Info>
  本接口为异步接口。提交成功后从 `data[0].task_id` 获取任务 ID，再通过 [任务查询](/cn/api-reference/tasks/status) 获取结果。建议每 3–5 秒轮询一次，整体等待超时设为 3 分钟；状态为 `completed` 或 `failed` 时停止轮询。
</Info>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.apimart.ai/v1/images/generations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "mai-image-2.6",
      "prompt": "黄昏时分的大学校园海报，写实摄影风格，电影感光线",
      "size": "16:9",
      "resolution": "2K"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.apimart.ai/v1/images/generations",
      headers={"Authorization": "Bearer <token>"},
      json={
          "model": "mai-image-2.6",
          "prompt": "黄昏时分的大学校园海报，写实摄影风格，电影感光线",
          "size": "16:9",
          "resolution": "2K"
      }
  )
  response.raise_for_status()
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.apimart.ai/v1/images/generations", {
    method: "POST",
    headers: {
      Authorization: "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "mai-image-2.6",
      prompt: "黄昏时分的大学校园海报，写实摄影风格，电影感光线",
      size: "16:9",
      resolution: "2K"
    })
  });
  if (!response.ok) throw new Error(await response.text());
  console.log(await response.json());
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "data": [
      {
        "status": "submitted",
        "task_id": "task_01K..."
      }
    ]
  }
  ```
</ResponseExample>

## 请求头

<ParamField header="Authorization" type="string" required>
  Bearer 认证，格式为 `Bearer <token>`，其中 `<token>` 为你的 APIMart API Key。
</ParamField>

## 请求参数

<ParamField body="model" type="string" required>
  模型 ID：`mai-image-2.6` 或 `mai-image-2.6-flash`。
</ParamField>

<ParamField body="prompt" type="string" required>
  图片描述或编辑指令，支持中文和英文，最长约 32,000 tokens（不是字符数）。
</ParamField>

<ParamField body="size" type="string" default="1:1">
  支持宽高比（如 `16:9`）、像素尺寸（如 `1536x1024`）或 `auto`。

  * 宽高比：支持 `1:4` 至 `4:1` 范围内的任意整数比，与 `resolution` 配合使用。
  * 像素尺寸：支持 `宽x高`、`宽*高`、`宽×高` 写法，此时不使用 `resolution` 决定尺寸。
  * `auto`：由模型根据提示词选择宽高比。

  仅用于文生图；传入参考图时，输出尺寸由模型决定。
</ParamField>

<ParamField body="resolution" type="string" default="1K">
  支持 `1K`、`2K`，兼容小写。不支持 `4K` 等其他档位，传入不支持的值会返回 HTTP 400。

  文生图使用宽高比时，此参数决定尺寸档位；使用精确像素时不参与尺寸计算。图生图不能通过此参数指定输出尺寸。
</ParamField>

<ParamField body="width" type="integer">
  精确像素宽度，必须与 `height` 成对提供。两者优先于 `size` 和 `resolution` 决定文生图尺寸。

  宽、高均至少为 768，总像素不超过 2,359,296。建议使用 32 的倍数，否则实际输出宽高会分别向下取整到 32 的倍数。

  图生图不使用此参数决定输出尺寸。
</ParamField>

<ParamField body="height" type="integer">
  精确像素高度，必须与 `width` 成对提供，尺寸约束同上。图生图不使用此参数决定输出尺寸。
</ParamField>

<ParamField body="image_urls" type="string[]">
  参考图片列表，最多 5 张。不传为文生图；传入一张为单图编辑，传入多张为多图合成。

  每项支持公网可访问的 HTTP(S) 图片直链，或 Base64 Data URL，例如 `data:image/png;base64,...`。

  支持 JPEG、PNG；WEBP、GIF 会自动转换为 PNG。图片 URL 必须能被公网访问，否则任务会失败。

  **图生图输出尺寸由模型根据参考图决定**，约 100 万像素，比例贴近参考图；`size`、`resolution`、`width`、`height` 均不能指定图生图输出尺寸。
</ParamField>

<ParamField body="auto_aspect_ratio" type="boolean" default="false">
  设为 `true` 时，让模型根据提示词选择宽高比，等价于 `size: "auto"`。
</ParamField>

<ParamField body="web_grounding" type="boolean" default="false">
  设为 `true` 时，在生成前检索实时信息，适用于真实人物、地点或事件相关的图片。
</ParamField>

<ParamField body="n" type="integer" default="1">
  只支持 `1`。需要多张图片时请分别提交任务，传入大于 1 的值会返回 HTTP 400。
</ParamField>

## 文生图尺寸选择

| 需求 | 参数 |
| - | - |
| 默认正方形 | 不传尺寸参数：`1:1` + `1K`，输出 1024×1024 |
| 分辨率档位 + 宽高比 | `size: "16:9"`、`resolution: "2K"` |
| 精确像素 | `size: "1536x1024"`，或 `width: 1536`、`height: 1024` |
| 自动选择比例 | `size: "auto"` 或 `auto_aspect_ratio: true` |

文生图的尺寸优先级为：成对的 `width` / `height` → 精确像素形式的 `size` → 宽高比形式的 `size` 与 `resolution` 组合。

### 档位与宽高比

| 宽高比 | 1K | 2K |
| - | - | - |
| 1:1 | 1024×1024 | 1536×1536 |
| 4:3 / 3:4 | 1152×864 / 864×1152 | 1760×1312 / 1312×1760 |
| 3:2 / 2:3 | 1248×832 / 832×1248 | 1856×1248 / 1248×1856 |
| 16:9 / 9:16 | 1344×768 / 768×1344 | 2048×1152 / 1152×2048 |
| 2:1 / 1:2 | 1536×768 / 768×1536 | 2144×1056 / 1056×2144 |
| 21:9 / 9:21 | 1792×768 / 768×1792 | 2336×992 / 992×2336 |
| 4:1 / 1:4 | 3072×768 / 768×3072 | 3072×768 / 768×3072 |

宽高会换算为 32 的倍数。由于短边至少为 768，宽高比较极端时，`1K` 档也可能超过约 100 万像素，并按实际输出像素对应的 token 用量计费。

### 精确像素约束

* 宽、高均至少为 768。
* 宽 × 高不超过 2,359,296（1536 × 1536）。
* 宽、高会分别向下取整到 32 的倍数。例如 `1000x1000` 实际输出为 `992x992`；需要精确尺寸时请直接传 32 的倍数。

支持 `1536x1024`、`2048x1152`、`3072x768` 等尺寸。`512x512` 因边长过小被拒绝，`2048x2048` 因总像素超限被拒绝。

<Warning>
  最大限制是**总像素数**，不是每条边都不能超过 1536。因此 `2048x1152`、`3072x768` 可以使用，但不支持 4K 档。以上尺寸配置仅适用于文生图。
</Warning>

## 请求示例

### 精确像素与联网增强

```json theme={null}
{
  "model": "mai-image-2.6-flash",
  "prompt": "夜晚的埃菲尔铁塔与烟花，旅行海报风格",
  "width": 2048,
  "height": 1152,
  "web_grounding": true
}
```

### 单图编辑

```json theme={null}
{
  "model": "mai-image-2.6",
  "prompt": "把自行车改成蓝色，并在旁边加一只小狗",
  "image_urls": ["https://example.com/bicycle.png"]
}
```

### 多图合成

```json theme={null}
{
  "model": "mai-image-2.6-flash",
  "prompt": "将两张参考图合成为干净、具有未来感的产品照片",
  "image_urls": [
    "https://example.com/first.png",
    "https://example.com/second.jpg"
  ]
}
```

请将示例中的图片 URL 替换为实际可访问的地址。

## 不支持的参数

`quality`、`style`、`background`、`output_format`、`response_format`、`mask_url` 不受支持，传入会被忽略。输出固定为 PNG，不支持蒙版编辑。

## 提交响应

<ResponseField name="code" type="integer">
  响应状态码，成功为 `200`。
</ResponseField>

<ResponseField name="data" type="array">
  任务提交结果。

  <Expandable title="显示任务字段">
    <ResponseField name="status" type="string">
      提交成功时为 `submitted`，不代表图片生成完成。
    </ResponseField>

    <ResponseField name="task_id" type="string">
      任务 ID，用于查询状态和结果。
    </ResponseField>
  </Expandable>
</ResponseField>

## 查询任务结果

```bash theme={null}
curl --request GET \
  --url https://api.apimart.ai/v1/tasks/task_01K... \
  --header 'Authorization: Bearer <token>'
```

成功响应示例（图片 URL 为占位示例）：

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01K...",
    "status": "completed",
    "progress": 100,
    "result": {
      "images": [
        {
          "url": ["https://example.com/generated-image.png"]
        }
      ]
    }
  }
}
```

| 状态 | 处理方式 |
| - | - |
| `pending` | 排队中，继续轮询 |
| `processing` | 处理中，继续轮询 |
| `completed` | 成功，从 `data.result.images[0].url` 数组获取图片链接 |
| `failed` | 失败，从 `data.error.message` 获取原因，停止轮询；费用全额退回 |

## 计费说明

按实际输入、输出 token 用量计费，具体单价以[模型定价](https://apimart.ai/pricing)为准。

* 图片输出 token = 实际输出宽 × 高 ÷ 1024。例如 1024×1024 对应 1024 tokens，1536×1536 对应 2304 tokens。
* 每张参考图输入 token 约为参考图宽 × 高 ÷ 1024；文字提示词也计入输入用量。
* 提交时按档位预扣费用，成功后按实际 token 用量多退少补。
* 任务失败时自动全额退款；提交阶段拒绝的参数错误不创建任务、不扣费。

## 常见错误

| HTTP | 原因与处理方式 |
| - | - |
| 400 | `resolution` 不支持，例如 `4K`；请使用 `1K` 或 `2K` |
| 400 | 宽或高小于 768，或总像素超过 2,359,296 |
| 400 | 只传了 `width` 或 `height`，两者必须成对提供 |
| 400 | 宽高比超出 `1:4` 至 `4:1`，或 `size` 格式无法识别 |
| 400 | `n` 大于 1，或参考图超过 5 张 |

任务失败时请检查图片下载或内容安全相关错误，修改提示词或参考图后重试。涉及未成年人的写实照片编辑可能被内容安全策略拦截。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.