> ## Documentation Index
> Fetch the complete documentation index at: https://gccai.heqingsong.uk/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://gccai.heqingsong.uk/pricing)为准。

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

```bash cURL theme={null}
curl --request POST \
  --url https://gccai.heqingsong.uk/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://gccai.heqingsong.uk/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://gccai.heqingsong.uk/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());
```

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

## 请求头

**Authorization** `string` *required*

Bearer 认证，格式为 `Bearer <token>`，其中 `<token>` 为你的 GccAi API Key。

## 请求参数

**model** `string` *required*

模型 ID：`mai-image-2.6` 或 `mai-image-2.6-flash`。

**prompt** `string` *required*

图片描述或编辑指令，支持中文和英文，最长约 32,000 tokens（不是字符数）。

**size** `string` (default: 1:1)

支持宽高比（如 `16:9`）、像素尺寸（如 `1536x1024`）或 `auto`。

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

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

**resolution** `string` (default: 1K)

支持 `1K`、`2K`，兼容小写。不支持 `4K` 等其他档位，传入不支持的值会返回 HTTP 400。

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

**width** `integer`

精确像素宽度，必须与 `height` 成对提供。两者优先于 `size` 和 `resolution` 决定文生图尺寸。

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

图生图不使用此参数决定输出尺寸。

**height** `integer`

精确像素高度，必须与 `width` 成对提供，尺寸约束同上。图生图不使用此参数决定输出尺寸。

**image\_urls** `string[]`

参考图片列表，最多 5 张。不传为文生图；传入一张为单图编辑，传入多张为多图合成。

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

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

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

**auto\_aspect\_ratio** `boolean` (default: false)

设为 `true` 时，让模型根据提示词选择宽高比，等价于 `size: "auto"`。

**web\_grounding** `boolean` (default: false)

设为 `true` 时，在生成前检索实时信息，适用于真实人物、地点或事件相关的图片。

**n** `integer` (default: 1)

只支持 `1`。需要多张图片时请分别提交任务，传入大于 1 的值会返回 HTTP 400。

## 文生图尺寸选择

| 需求 | 参数 |
| - | - |
| 默认正方形 | 不传尺寸参数：`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 档。以上尺寸配置仅适用于文生图。

## 请求示例

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

```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，不支持蒙版编辑。

## 提交响应

**code** `integer`

响应状态码，成功为 `200`。

**data** `array`

任务提交结果。

**显示任务字段**

**status** `string`

提交成功时为 `submitted`，不代表图片生成完成。

**task\_id** `string`

任务 ID，用于查询状态和结果。

## 查询任务结果

```bash theme={null}
curl --request GET \
  --url https://gccai.heqingsong.uk/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://gccai.heqingsong.uk/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.