图生图与参考图

推荐 POST /v1/images/edits/async。同一接口接收参考图与提示词，创建任务后继续使用统一图片任务查询路径。

multipart 文件上传

bash

curl --fail-with-body --max-time 120 \
  https://api.manxiaobai.online/v1/images/edits/async \
  -H "Authorization: Bearer $MXB_API_KEY" \
  -F 'model=gpt-image-2.5' \
  -F 'prompt=保持茶壶形状与颜色，将背景改为浅绿色' \
  -F 'size=1024x1024' \
  -F 'n=1' \
  -F 'image=@reference.png;type=image/png'

在命令执行目录放置真实 reference.png；不要把 JPEG 文件只改后缀伪装成 PNG。curl 自动设置 multipart Content-Type 和 boundary。

字段	形式	说明
model	文本	完整模型 ID
prompt	文本	描述要保留与修改的部分
image	文件	推荐的单参考图字段
size	文本	按模型选择的请求尺寸
n	文本 `1`	推荐每个任务一张输出
quality	文本，可选	只在已确认模型/渠道支持时使用

Gemini multipart 支持 PNG、JPEG、WebP、BMP 的类型识别，单张参考图大小上限为 25 MiB；渠道可能有更小限制。总 HTTP 请求体也受网关限制，JSON Base64 会扩大体积。GPT 上传能力随渠道不同，建议优先用单张 PNG/JPEG 验证。

JSON 参考图

GPT 2.5 与 Gemini Flash 的以下 JSON 编辑形式已有真实成功记录，不能据此推定所有 GPT 渠道都支持同一种 JSON 扩展。

json

{
  "model": "gemini-3.1-flash-image-preview-1k",
  "prompt": "保留主体，把背景改成干净的白色",
  "images": [
    {"image_url": "data:image/png;base64,替换为完整图片的Base64内容"}
  ],
  "size": "1024x1024",
  "n": 1
}

images[].image_url 是完整 Data URL，不能包含文件路径或省略的 ...。要避免手工拼接，使用完整代码中的 --reference reference.png。

Gemini 还支持由服务端读取公开 HTTP/HTTPS 图片 URL；私有地址、无法解析的域名、要求 Cookie 的图片和过多重定向会被拒绝。图片 URL 必须在生成期间可访问。参考图上传或读取失败时，应停止并修复输入，不能默默改成纯文生图。

多参考图与遮罩

Gemini 可构造多参考图输入，multipart 可重复 image/image[] 字段。不同模型/渠道的数量与行为没有统一承诺；本手册的最小稳定示例使用单参考图。

mask、精确局部重绘、透明区域语义和多图顺序依赖具体渠道能力。当前不能把它们列为所有模型统一支持的编辑能力；有此需求时先对目标模型与分组做小规模验证。

同步与错误

将路径改为 /v1/images/edits 且不加异步开关即为同步请求。异步编辑失败也可能发生在 HTTP 202 之后，因此必须轮询到终态，检查 error.message 和图片结果，而不是只检查上传成功。