跳转到主要内容
POST

Authorizations

string
必填
所有接口均需要使用 Bearer Token 进行认证获取 API Key:访问 API Key 管理页面 获取您的 API Key使用时在请求头中添加:

Body

string
默认值:"mai-image-2.7"
必填
图像生成模型名称两个模型的能力和参数完全相同。
boolean
默认值:"false"
是否在提交图片任务前执行内容审核。
  • true:使用 omni-moderation-latest 审核提示词和输入图片
  • false 或不传:不发起审核请求,不增加审核成本与延迟(默认)
string
必填
图像生成的文本描述或编辑指令
  • 支持中英文,建议详细描述
  • 最长 20,000 字符,超出返回 400
  • 不能为空或纯空白
integer
默认值:"1"
生成图片张数取值:1
每次只能生成 1 张,需要多张请分别提交任务;传入 0、负数或大于 1 的值会返回 400
string
默认值:"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(总像素超限)
不支持 auto,传入会返回 400
string
默认值:"1K"
输出分辨率档位,仅在 size 为宽高比时生效可选值:1K / 2K(兼容小写)size × resolution → 实际像素对应关系:
不支持 4K,传入其他档位会返回 400。由于短边至少为 768,比 2:1 更扁的比例在 1K 档实际像素会超过约 100 万。
integer
精确像素宽度,必须与 height 成对传入
  • 优先级最高,同时传入时会覆盖 size 和 resolution
  • 约束与 size 像素尺寸相同:宽、高均 ≥ 768,总像素 ≤ 4,194,304
  • 仅对文生图生效
integer
精确像素高度,必须与 width 成对传入,约束同 width
array
参考图数组,传入后走图生图模式
  • 传 1 张为单图编辑,传多张为多图合成
string
背景类型可选值:auto / opaque,效果与不传相同
透明背景 transparent 暂未开放,传入 transparent 或其他值会返回 400
auto_aspect_ratio: true、web_grounding: true 不支持,传入会返回 400。quality、style、output_format、response_format、mask_url 不支持,会被忽略。输出固定为 PNG。

使用场景示例

文生图(最简请求) 默认 1:1 + 1K,输出 1024×1024。
文生图(指定比例 + 2K)
文生图(精确像素)
单图编辑
多图合成(URL + base64 混填)

Response

integer
响应状态码
array
返回数据数组

查询任务结果

提交成功后返回 task_id,通过 GET /v1/tasks/{task_id} 轮询任务状态,详见 任务查询接口。建议每 3–5 秒轮询一次,整体超时设为 3 分钟。

成功响应示例

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

任务状态说明