MAI Image 2.6 API 指南：生成、编辑与任务轮询

首次接入 MAI Image 2.6，先确定应用遵循哪项服务契约。Microsoft 文档介绍了通过 Foundry 进行生成与编辑。在 reAPI，两种操作都使用图像生成接口：编辑时添加参考图 URL，再轮询返回的任务 ID。不同服务中的模型名称相近，但认证方式、请求体和响应不能混用。^[1]

本指南遵循 reAPI 的 mai-image-2.6 契约。先完成一个纯文本请求，再添加参考图处理或自动构图。这样在请求失败时，可以检查一个足够小的接入流程。实现时参考完整参数文档；MAI Image 2.6 试用界面提供相同控件与当前预估费用。^[2]

要点速览

向图像接口提交 mai-image-2.6 和非空提示词。每次请求生成一张图片。^[2]
使用宽高比搭配 1K 或 2K，或有效的成对像素尺寸。接口不接受 4K。^[2]
参考图编辑可提供最多五个有序的公开图片 URL。使用参考图时，输出尺寸由模型选择。^[2]
保存任务 ID，轮询至 completed 或 failed。提交响应不包含完成的图片。^[2]
显示费用属于预估。完成后结算预留金额；通过 ?include=billing 可读取精确账单。^[2]

发起第一次 MAI Image 2.6 请求

创建 reAPI 密钥，并以 REAPI_API_KEY 保存在服务端环境中。请求须包含模型和非空提示词。以下示例用明确的像素尺寸请求方形图片，便于核对画面。它只是请求示例，不保证每个生成物体都完美符合描述。

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer $REAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mai-image-2.6",
    "prompt": "A matte ivory ceramic teapot on a pale blue table, soft daylight, product photography.",
    "width": 1024,
    "height": 1024,
    "n": 1
  }'

API ID 在 6 前使用小数点。模型页 URL 使用 /models/mai-image-2-6；将连字符形式的 slug 复制到请求中，会得到不同的字符串。提交成功后立即保存任务 id，用于获取结果、识别失败或在客户端断线后恢复查询。每次请求生成一张图片；增加 n 并不能获得受支持的批量生成。^[2]

不要将密钥放入浏览器代码。前端可将用户需求发送到后端，由后端添加 Bearer token 并提交请求。根据访问设计，向前端返回应用作业标识或任务 ID。不要把密钥放进查询字符串、截图或复制的错误报告。

提交成功只表示请求已被接受，图片尚未完成。轮询 GET /api/v1/tasks/:id，直到任务进入 completed 或 failed。完成任务通过 output.image_urls 提供图片，失败任务提供 error。旧版 usage.credits 会舍入为整数积分。精确记账时使用 ?include=billing，查看 billing.credits_exact、billing.cost_usd，以及存在时的已扣费和差额信息。轮询原任务不会再次提交生成。^[2]

const taskId = submittedTask.id;
const headers = { Authorization: `Bearer ${process.env.REAPI_API_KEY}` };
const deadline = Date.now() + 5 * 60 * 1000;

while (Date.now() < deadline) {
  const response = await fetch(
    `https://reapi.ai/api/v1/tasks/${encodeURIComponent(taskId)}`,
    { headers },
  );
  if (!response.ok) {
    throw new Error(`Task lookup failed: HTTP ${response.status}; task ${taskId}`);
  }
  const task = await response.json();
  if (task.status === 'completed') {
    console.log(task.output.image_urls, task.usage);
    break;
  }
  if (task.status === 'failed') {
    throw new Error(JSON.stringify({ taskId, error: task.error }));
  }
  await new Promise((resolve) => setTimeout(resolve, 3000));
}

这里的 submittedTask 是解析后的成功提交响应。五分钟期限只是应用示例，不是延迟保证。超过期限时保留 taskId，显示应用已停止等待。任务没有报告失败时，不要将生成本身标为失败。生产客户端应在循环结束后返回单独的超时状态，并允许刷新已有任务的状态。

提交后的网络错误还可能造成另一种不确定性：连接断开前，服务端可能已接受请求。自动重试所有 POST 可能创建额外计费任务。将提交与轮询分开，并在执行可选界面操作前保存返回的 ID。

选择接口接受的尺寸

纯文本 MAI Image 2.6 请求可使用宽高比与分辨率档位，或明确像素尺寸。接口接受 1K 和 2K，不接受 4K。指定尺寸时，每边至少 768 像素，总面积不得超过 2,359,296 像素。宽高比使用正整数，范围为 1:4 至 4:1。^[2]

请求	含义
`size: "16:9", resolution: "2K"`	所选档位的横版画面
`size: "1536x1024"`	明确像素尺寸
`width: 1024, height: 1024`	成对指定画布尺寸
`size: "auto"`	让模型推断画面比例
`width: 2048, height: 2048`	无效：像素面积过大

成对 width 和 height 优先于 size 中的像素尺寸，后者优先于宽高比加分辨率。尽量只用一种明确的尺寸指定方式。例如，同时传入 width: 1024, height: 1024 与 size: "16:9"，即使文档中的优先级能处理请求，仍表达了矛盾意图。应用表单可以避免这种混淆。

尺寸会向下取整至 32 的倍数。因此按尺寸规则，请求 1000 × 1000 对应 992 × 992。如果排版需要精确交付尺寸，应在请求中选用有效倍数，并检查下载文件的尺寸。后续裁切或缩放应作为应用中的独立步骤。^[2]

从生成转向参考图编辑

在 MAI Image 2.6 请求中添加 image_urls，提供视觉参考。reAPI 接口接受最多五个公开 HTTP(S) 图片 URL。提示词仍为必填。保持顺序一致，并说明哪张图提供场景、主体或风格。^[2]

{
  "model": "mai-image-2.6",
  "prompt": "Use the first image as the room and the second as the chair. Replace the chair beside the window. Preserve the floor, window, and camera view.",
  "image_urls": [
    "https://example.com/room.jpg",
    "https://example.com/chair.jpg"
  ],
  "web_grounding": false
}

示例 URL 必须替换为可访问的图片文件。优先使用 JPEG 或 PNG。需要登录才能打开的 URL 不适合作为本请求的参考图。请检查 URL 返回的是预期图片字节，而不是 HTML 查看器或已过期的访问页面。

参考图编辑的尺寸规则不同：模型选择输出尺寸，size、resolution、width 和 height 不控制输出。在原本纯文本的请求中加入参考图，不仅改变视觉信息，也改变应用能对输出画布作出的承诺。^[2]

不要将“保持房间不变”理解为像素完全一致的保证。检查编辑物体、附近边缘、反射和应保留的特征。产品流程中还应单独检查标志、标签与实际比例。这些是建议的验收项，不表示本指南实测了模型在这些任务上的准确率。

有目的地使用自动构图与网页上下文

auto_aspect_ratio: true 让 MAI Image 2.6 根据提示词推断画面，size: "auto" 也有相同作用。它适合探索构图，但后续需要固定画布时不太合适。自动选择也会使完成前的输出像素数不确定。

web_grounding 是独立布尔参数，默认为 false。Microsoft 将网页上下文描述为模型创作输入的一部分，但开启开关不代表画面中的每个标签或事实都权威可靠。请核查对最终素材重要的信息。^[3]

两个开关都不能代替清晰的提示词。先说明主体、构图、材质和修改目标，再开启服务于该需求的控制项。记录提交值，有助于区分提示词修改和设置变化。

自动重试前先理解预估费用

MAI Image 2.6 费用随输入和生成像素变化。reAPI 提交时预留预估金额，完成后结算。最终费用可能更低，也可能更高。参考图和模型选择的尺寸，使报价不能视为固定的每图价格。^[2]

按计划发送的请求查看模型页当前预估。独立的价格与 Flash 指南解释了方形图、参考图编辑和宽幅图为何需要不同预算。本指南不在示例代码中固定费率。

任务契约规定生成失败会退款。已完成但不合心意的图片仍属于完成的生成。因此，多次创意尝试应按独立任务预算。记录采用的输出及尝试次数，评估可用素材的成本，而不只比较单次提交价格。

Microsoft Learn. 在 Microsoft Foundry 部署和使用 MAI 图像模型。 获取于 2026 年 10 月 9 日： learn.microsoft.com/azure/foundry/foundry-models/how-to/use-foundry-models-mai-image.
reAPI. MAI Image 2.6 请求、尺寸、轮询与计费契约。 核对于 2026 年 10 月 9 日： reapi.ai/docs/mai-image-2-6.
Microsoft AI. MAI-Image-2.6. 获取于 2026 年 10 月 9 日： microsoft.ai/models/mai-image-2-6.