# mai-image 图像生成
> 文生图与多图参考
> 参考图最多 5 张
> 支持联网检索实时信息
`POST /v1/images/generations`
## 认证
- `Authorization` (string / 必填) — 所有接口均使用 Bearer Token 进行认证。 获取 API Key：[访问控制台](https://api.oairoute.com/keys) 创建。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_OAIRoute_KEY ```
## 请求结构
请求体是平铺的 JSON，创作字段与输出字段都在顶层，没有 `content` 数组包装。
## 支持的场景
| 场景 | 字段组合 |
|---|---|
| 文生图 | `prompt` |
| 单图编辑 | `prompt` + `image`（1 张） |
| 多图合成 | `prompt` + `image`（2 到 5 张） |
| 实时信息配图 | `prompt` + `web_grounding: true` |
带参考图后，输出尺寸完全由模型依据参考图决定，约 100 万像素，比例贴近参考图，`size`、`resolution`、`width`、`height` 都无法指定。
## 请求参数
> **Note:** 
> 提交成功只返回任务 ID，不含图片本身。拿结果用 `task_id` 轮询[获取任务状态](../tasks/status.html)，图片地址在 `result.images[0].url`，该地址会过期，请及时转存。
- `model` (string / 必填) — 取值 `mai-image-2.6` 或 `mai-image-2.6-flash`。
- `prompt` (string / 必填) — 描述或编辑指令，中英文均可，上限约 32000 token。
- `size` (string / 可选) — 默认 `1:1`。 可写宽高比（整比范围 1:4 到 4:1）、精确像素（如 `1536x1024`，也支持 `*` 与 `×` 分隔），或 `auto`。 只在文生图生效，传入参考图后输出尺寸由模型决定。
- `resolution` (string / 可选) — 取值 `1K`（默认）、`2K`，兼容小写。`4K` 等其他档位返回 400。
- `width` (integer / 可选) — 必须与 `height` 成对，优先级高于 `size` 与 `resolution`。 最小 768，宽高乘积上限 2359296，建议取 32 的倍数，否则向下取整。
- `height` (integer / 可选) — 约束与 `width` 相同。
- `image` (string | string[] / 可选) — 参考图，最多 5 张。 公网直链或 Base64 Data URL。JPEG、PNG 直接使用，WEBP 与 GIF 自动转 PNG。
- `auto_aspect_ratio` (boolean / 可选) — 为 `true` 时由模型按提示词选比例，等同 `size: "auto"`，默认 `false`。
- `web_grounding` (boolean / 可选) — 生成前检索实时信息，适合真实人物、地点与事件，默认 `false`。
- `n` (integer / 可选) — 只能为 `1`，大于 1 返回 400。
## 不生效的字段
`quality`、`style`、`background`、`output_format`、`response_format`、`mask_url` 传入会被忽略。输出固定为 PNG，不支持蒙版编辑。
## 尺寸约束
`width` 与 `height` 最小 768，宽高乘积上限 2359296。上限针对总像素而非单边，因此长边可以超过 1536，例如 `3072x768` 合法，而 `2048x2048` 超限。
## 响应
提交成功返回受理结构：
```json
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
- `code` (integer / 总是返回) — 状态码，`200` 表示任务已受理。
- `data` (array / 总是返回) — 本次提交的任务列表。
- `data[].status` (string / 总是返回) — 受理状态，提交成功时为 `submitted`。
- `data[].task_id` (string / 总是返回) — 任务 ID，用它轮询结果。
完成态返回：
```json
{
  "code": 200,
  "data": {
    "id": "task_01K8SGYNNNVBQTXNR4MM964S7K",
    "status": "completed",
    "progress": 100,
    "result": {
      "images": [
        { "url": ["https://cdn.oairoute.com/f/image/task_01K8_0.png"], "expires_at": 1763174708 }
      ]
    },
    "created": 1763088289,
    "completed": 1763088302
  }
}
```
## 错误码
| HTTP | 含义 |
|---|---|
| 400 | 参数错误，type 为 invalid_request_error |
| 401 | Token 缺失或无效，type 为 authentication_error |
| 402 | 余额不足，type 为 payment_required |
| 429 | 触发限流 |
更多状态码与重试建议见[错误码与限流](../../support/errors.html)，常见报错的排查步骤见[常见问题](../../support/faq.html)。
## 支持的模型列表
| 模型 ID | 定位 |
|---|---|
| `mai-image-2.6` | 高画质版，画质优先 |
| `mai-image-2.6-flash` | 快速版，速度更快、成本更低，画质略低 |
两个模型参数与能力一致，每次调用只出 1 张图。
> **Note:** 完整模型目录（含价格、分辨率上限）可读取 `GET https://api.oairoute.com/api/pricing`。
## 使用示例
**文生图{Text to image}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/images/generations' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "mai-image-2.6",
  "prompt": "北欧风格客厅，浅色木地板，大窗自然光",
  "size": "16:9",
  "resolution": "2K"
}'
```
**文生图{Text to image}::Python**
```
import requests
url = "https://api.oairoute.com/v1/images/generations"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "mai-image-2.6",
  "prompt": "北欧风格客厅，浅色木地板，大窗自然光",
  "size": "16:9",
  "resolution": "2K"
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**文生图{Text to image}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "mai-image-2.6",
  "prompt": "北欧风格客厅，浅色木地板，大窗自然光",
  "size": "16:9",
  "resolution": "2K"
}),
});
console.log(await res.json());
```
**200 文生图{Text to image}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
**单图编辑{Image edit}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/images/generations' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "mai-image-2.6",
  "prompt": "把墙面换成暖白色，家具保持不变",
  "image": [
    "https://example.com/room.jpg"
  ]
}'
```
**单图编辑{Image edit}::Python**
```
import requests
url = "https://api.oairoute.com/v1/images/generations"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "mai-image-2.6",
  "prompt": "把墙面换成暖白色，家具保持不变",
  "image": [
    "https://example.com/room.jpg"
  ]
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**单图编辑{Image edit}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "mai-image-2.6",
  "prompt": "把墙面换成暖白色，家具保持不变",
  "image": [
    "https://example.com/room.jpg"
  ]
}),
});
console.log(await res.json());
```
**200 单图编辑{Image edit}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
**多图合成{Multi compose}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/images/generations' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "mai-image-2.6",
  "prompt": "把两款产品放在同一个展示台上，光线统一",
  "image": [
    "https://example.com/p1.png",
    "https://example.com/p2.png"
  ]
}'
```
**多图合成{Multi compose}::Python**
```
import requests
url = "https://api.oairoute.com/v1/images/generations"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "mai-image-2.6",
  "prompt": "把两款产品放在同一个展示台上，光线统一",
  "image": [
    "https://example.com/p1.png",
    "https://example.com/p2.png"
  ]
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**多图合成{Multi compose}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "mai-image-2.6",
  "prompt": "把两款产品放在同一个展示台上，光线统一",
  "image": [
    "https://example.com/p1.png",
    "https://example.com/p2.png"
  ]
}),
});
console.log(await res.json());
```
**200 多图合成{Multi compose}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
**实时信息配图{Grounded image}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/images/generations' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "mai-image-2.6",
  "prompt": "描述今天的天气实况并配一张示意图",
  "web_grounding": true,
  "size": "16:9"
}'
```
**实时信息配图{Grounded image}::Python**
```
import requests
url = "https://api.oairoute.com/v1/images/generations"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "mai-image-2.6",
  "prompt": "描述今天的天气实况并配一张示意图",
  "web_grounding": true,
  "size": "16:9"
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**实时信息配图{Grounded image}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "mai-image-2.6",
  "prompt": "描述今天的天气实况并配一张示意图",
  "web_grounding": true,
  "size": "16:9"
}),
});
console.log(await res.json());
```
**200 实时信息配图{Grounded image}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```