> ## 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.7 图像生成

>  - 异步处理模式，返回任务ID用于后续查询
- 支持文生图 / 单图编辑 / 多图合成，参考图最多 5 张
- 提供高质量版 `mai-image-2.7` 与快速版 `mai-image-2.7-flash`，能力与参数相同
- 通过 `size`（宽高比）+ `resolution`（`1K` / `2K`）控制输出尺寸，也可直接指定像素
- 单张最大 2048×2048（约 419 万像素），每次生成 1 张 

```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.7",
    "prompt": "黄昏时分的大学校园海报，写实摄影风格，电影感光线",
    "size": "16:9",
    "resolution": "2K"
  }'
```

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

url = "https://api.apimart.ai/v1/images/generations"

payload = {
    "model": "mai-image-2.7",
    "prompt": "黄昏时分的大学校园海报，写实摄影风格，电影感光线",
    "size": "16:9",
    "resolution": "2K"
}

headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript JavaScript theme={null}
const url = "https://api.apimart.ai/v1/images/generations";

const payload = {
  model: "mai-image-2.7",
  prompt: "黄昏时分的大学校园海报，写实摄影风格，电影感光线",
  size: "16:9",
  resolution: "2K"
};

const headers = {
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
};

fetch(url, {
  method: "POST",
  headers: headers,
  body: JSON.stringify(payload)
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));
```

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

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

func main() {
    url := "https://api.apimart.ai/v1/images/generations"

    payload := map[string]interface{}{
        "model":      "mai-image-2.7",
        "prompt":     "黄昏时分的大学校园海报，写实摄影风格，电影感光线",
        "size":       "16:9",
        "resolution": "2K",
    }

    jsonData, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("Authorization", "Bearer <token>")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}
```

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

```json 400 theme={null}
{
  "error": {
    "code": 400,
    "message": "参数错误：prompt 为空 / size 不合法 / resolution 不支持 / 像素越界等",
    "type": "invalid_request_error"
  }
}
```

```json 401 theme={null}
{
  "error": {
    "code": 401,
    "message": "身份验证失败，请检查您的API密钥",
    "type": "authentication_error"
  }
}
```

```json 402 theme={null}
{
  "error": {
    "code": 402,
    "message": "账户余额不足，请充值后再试",
    "type": "payment_required"
  }
}
```

```json 429 theme={null}
{
  "error": {
    "code": 429,
    "message": "请求过于频繁，请稍后再试",
    "type": "rate_limit_error"
  }
}
```

```json 500 theme={null}
{
  "error": {
    "code": 500,
    "message": "服务器错误",
    "type": "server_error"
  }
}
```

## Authorizations

**Authorization** `string` *required*

所有接口均需要使用 Bearer Token 进行认证

获取 API Key：

访问 [API Key 管理页面](https://apimart.ai/keys) 获取您的 API Key

使用时在请求头中添加：

```
Authorization: Bearer YOUR_API_KEY
```

## Body

**model** `string` *required* (default: mai-image-2.7)

图像生成模型名称

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

两个模型的能力和参数完全相同。

**nsfw\_check** `boolean` (default: false)

是否在提交图片任务前执行内容审核。

* `true`：使用 `omni-moderation-latest` 审核提示词和输入图片
* `false` 或不传：不发起审核请求，不增加审核成本与延迟（默认）

**prompt** `string` *required*

图像生成的文本描述或编辑指令

* 支持中英文，建议详细描述
* 最长 20,000 字符，超出返回 400
* 不能为空或纯空白

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

生成图片张数

取值：`1`

> [!WARNING]
>
> 每次只能生成 1 张，需要多张请分别提交任务；传入 `0`、负数或大于 1 的值会返回 400

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

图像比例或像素尺寸，仅对文生图生效

支持两种写法：

* **宽高比**：`1:4` 至 `4:1` 范围内的任意整数比，如 `1:1`、`16:9`、`9:16`、`21:9`，与 `resolution` 配合决定实际像素
* **像素尺寸**：`宽x高`（兼容 `宽*高`、`宽×高`），如 `2048x1152`，此时忽略 `resolution`

像素尺寸约束：

* 宽、高均 **≥ 768**
* 宽 × 高 **≤ 4,194,304**（2048×2048）
* 宽、高会各自向下取整到 32 的倍数，例如 `1000x1000` 实际输出 `992x992`

示例：✅ `2048x2048`、`2048x1152`、`2560x1536`；❌ `512x512`（边长小于 768）、`2080x2048`（总像素超限）

> [!WARNING]
>
> 不支持 `auto`，传入会返回 400

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

输出分辨率档位，仅在 `size` 为宽高比时生效

可选值：`1K` / `2K`（兼容小写）

`size × resolution` → 实际像素对应关系：

| size | `1K` | `2K` |
| - | - | - |
| `1:1` | 1024×1024 | 2048×2048 |
| `4:3` | 1152×864 | 2336×1760 |
| `3:4` | 864×1152 | 1760×2336 |
| `3:2` | 1248×832 | 2496×1664 |
| `2:3` | 832×1248 | 1664×2496 |
| `16:9` | 1344×768 | 2720×1536 |
| `9:16` | 768×1344 | 1536×2720 |
| `2:1` | 1536×768 | 2880×1440 |
| `1:2` | 768×1536 | 1440×2880 |
| `21:9` | 1792×768 | 3104×1312 |
| `9:21` | 768×1792 | 1312×3104 |
| `4:1` | 3072×768 | 4096×1024 |
| `1:4` | 768×3072 | 1024×4096 |

> [!WARNING]
>
> 不支持 `4K`，传入其他档位会返回 400。由于短边至少为 768，比 2:1 更扁的比例在 `1K` 档实际像素会超过约 100 万。

**width** `integer`

精确像素宽度，必须与 `height` 成对传入

* 优先级最高，同时传入时会覆盖 `size` 和 `resolution`
* 约束与 `size` 像素尺寸相同：宽、高均 ≥ 768，总像素 ≤ 4,194,304
* 仅对文生图生效

**height** `integer`

精确像素高度，必须与 `width` 成对传入，约束同 `width`

**image\_urls** `array`

参考图数组，传入后走图生图模式

* 传 1 张为单图编辑，传多张为多图合成

**详细说明**

* 最多 5 张参考图
* 支持 `图片 URL`（公网可访问的直链，不可访问会导致任务失败）
* 支持 `base64 data URI`（形如 `data:image/png;base64,...`）
* 支持 JPEG、PNG 格式，WEBP、GIF 会自动转换为 PNG
* 输出尺寸由模型根据参考图决定，`size` / `resolution` / `width` / `height` 对图生图不生效

**background** `string`

背景类型

可选值：`auto` / `opaque`，效果与不传相同

> [!WARNING]
>
> 透明背景 `transparent` 暂未开放，传入 `transparent` 或其他值会返回 400

> [!NOTE]
>
> `auto_aspect_ratio: true`、`web_grounding: true` 不支持，传入会返回 400。`quality`、`style`、`output_format`、`response_format`、`mask_url` 不支持，会被忽略。输出固定为 PNG。

## 使用场景示例

**文生图（最简请求）**

默认 `1:1` + `1K`，输出 1024×1024。

```json theme={null}
{
  "model": "mai-image-2.7",
  "prompt": "黄昏时分的大学校园海报，写实摄影风格，电影感光线"
}
```

**文生图（指定比例 + 2K）**

```json theme={null}
{
  "model": "mai-image-2.7",
  "prompt": "黄昏时分的大学校园海报，写实摄影风格，电影感光线",
  "size": "3:2",
  "resolution": "2K"
}
```

**文生图（精确像素）**

```json theme={null}
{
  "model": "mai-image-2.7-flash",
  "prompt": "白色大理石台面上的玻璃香水瓶，干净的产品摄影",
  "width": 2048,
  "height": 2048
}
```

**单图编辑**

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

**多图合成（URL + base64 混填）**

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

## Response

**code** `integer`

响应状态码

**data** `array`

返回数据数组

**属性**

**status** `string`

任务状态

* `submitted` - 已提交

**task\_id** `string`

任务唯一标识符，用于后续查询任务结果

## 查询任务结果

提交成功后返回 `task_id`，通过 `GET /v1/tasks/{task_id}` 轮询任务状态，详见 [任务查询接口](https://docs.apimart.ai/cn/api-reference/tasks/status.md)。建议每 3–5 秒轮询一次，整体超时设为 3 分钟。

### 成功响应示例

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01K...",
    "status": "completed",
    "progress": 100,
    "result": {
      "images": [
        {
          "url": [
            "https://upload.apimart.ai/f/image/xxxxxxxx.png"
          ],
          "expires_at": 1791539365
        }
      ]
    }
  }
}
```

取图方式：`data.result.images[0].url[0]`。图片链接在 `expires_at` 后过期，请尽快下载保存。

### 任务状态说明

| 状态 | 含义 |
| - | - |
| `pending` | 排队中，继续轮询 |
| `processing` | 生成中，继续轮询 |
| `completed` | 成功，`result.images` 可用 |
| `failed` | 失败，查看 `error.message` |


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