# MAI Image API：尺寸、改图与报错

Source: https://ofox.ai/zh/docs/develop/models/mai-image

微软的图像生成与编辑模型，共三款，通过 OpenAI 兼容接口调用，用法与 GPT Image 基本一致：文生图使用 `/v1/images/generations`，改图使用 `/v1/images/edits`。

## 模型选择

**模型 ID（调用时原样复制）**

- MAI Image 2.5 Pro: `microsoft/mai-image-2.5-pro` — 复杂构图、人物与物体一致性
- MAI Image 2.5: `microsoft/mai-image-2.5` — 精确的局部修改
- MAI Image 2.5 Flash: `microsoft/mai-image-2.5-flash` — 低延迟、批量生成

三款参数相同，实测生成 1024×1024 图片约需 12 至 25 秒。实时价格请参阅[模型页](https://ofox.ai/zh/models/microsoft/mai-image-2.5)。

## 文生图

**Python**

```python filename="mai_image.py"
import base64
from openai import OpenAI

client = OpenAI(api_key="YOUR_OFOX_API_KEY", base_url="https://api.ofox.ai/v1", timeout=600)

resp = client.images.generate(
    model="microsoft/mai-image-2.5-flash",
    prompt="白色桌面上的一个红苹果",
    size="1024x1024",
)

with open("output.png", "wb") as f:
    f.write(base64.b64decode(resp.data[0].b64_json))
```

**cURL**

```bash filename="Terminal"
curl https://api.ofox.ai/v1/images/generations \
  --max-time 600 \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "microsoft/mai-image-2.5-flash",
    "prompt": "白色桌面上的一个红苹果",
    "size": "1024x1024"
  }' | jq -r '.data[0].b64_json' | base64 --decode > output.png
```

## 尺寸（size）

**要点**:`size` 仅决定比例，输出约为 100 万像素，传入更大的尺寸不会提高分辨率。

| 请求的 `size` | 实际输出 |
|---|---|
| 不传 | 1024×1024 |
| `1024x1024`、`2048x2048`、`4096x4096` | 1024×1024 |
| `1536x1024` | 1248×832 |
| `1024x1536` | 832×1248 |
| `100x100` | 768×768 |

- 输出保留所请求的比例，总像素调整至约 100 万；传入过小的尺寸时输出 768×768。
- 如需更高分辨率，请选用 [Nano Banana Pro](https://ofox.ai/zh/docs/develop/models/nano-banana)（最高 4K）或 [GPT Image](https://ofox.ai/zh/docs/develop/models/gpt-image)。

## 改图

```bash filename="Terminal"
curl https://api.ofox.ai/v1/images/edits \
  --max-time 600 \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -F model=microsoft/mai-image-2.5 \
  -F prompt="把苹果改成紫色，其他保持不变" \
  -F image=@apple.jpg \
  | jq -r '.data[0].b64_json' | base64 --decode > apple_purple.png
```

参考图计入输入 token，见响应中的 `usage.input_tokens_details.image_tokens`。实测一张 768×768 的参考图计 576 个 token。

## 常见报错
| 报错 | 原因 | 处理方法 |
|---|---|---|
| 请求超时 | 客户端超时设置过短 | 将超时设置为 300 秒以上 |
| `404 model_not_found` | 模型 ID 拼写错误 | 从本页复制模型 ID |

需要多张图片时，请并发发起多次请求，每次生成一张。

## 常见问题

**MAI Image 能生成 2K 或 4K 的图吗？**

不能。size 只决定比例，输出总像素约 100 万。传 2048x2048 或 4096x4096 实测都输出 1024x1024。如需更高分辨率，请使用 Nano Banana Pro 或 GPT Image。

**MAI Image 怎么改图？**

使用 /v1/images/edits，以 multipart 表单上传 image 文件，写法与 GPT Image 相同。