图生图与参考图

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

multipart 文件上传

bash

curl --fail-with-body --max-time 120 \
  https://openpix.cc/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`	普通图片建议1；MJ使用JSON、n=1仍返回多张
quality	文本，可选	只在已确认模型/渠道支持时使用

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

JSON 参考图

GPT 图片的 AZ/OAI 相关接入现已兼容 JSON 的 image/images、HTTP(S) URL、Data URL 与 b64_json，并有双参考图实测；Gemini 也有 JSON 参考图成功记录。具体支持仍按型号和分组。MJ/Seedream 使用字符串数组，见各自专章。

json

{
  "model": "gemini-3.1-flash-image-preview",
  "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 和图片结果，而不是只检查上传成功。

JSON 与 multipart：两张图完整对照

GPT 的 JSON 编辑可下载 gpt-reference.json。prompt 是顶层非空字符串，images 每项包含 image_url。替换两张素材地址后，POST /v1/images/edits/async。不要用空字符串、数组或 messages 代替 prompt。

本地文件用 multipart 时：

bash

curl --fail-with-body --max-time 120 \
  https://openpix.cc/v1/images/edits/async \
  -H "Authorization: Bearer $MXB_API_KEY" \
  -F 'model=gpt-image-2.5-sunburst' \
  -F 'prompt=保留图一产品造型，采用图二配色，制作竖版海报' \
  -F 'size=1024x1536' -F 'quality=high' -F 'n=1' \
  -F 'image[]=@product.png;type=image/png' \
  -F 'image[]=@palette.png;type=image/png'

curl会设置带boundary的Content-Type，不能另写 application/json；prompt使用普通表单文本，不要把它作为文件部分上传。单图用image，多图用有序image[]。

AZ/OAI这一JSON转换路径最多16张、单图50 MiB、总表单128 MiB，支持PNG/JPEG/WebP；这些是该路径上限，不能当作所有其他型号都接受这么多或这么大的图片。Gemini单张25 MiB、MJ最多5张、Seedream Lite/Pro分别6/10张，格式也不同。接近总请求上限时还要考虑Base64膨胀与网关限制。

出现 prompt is required 怎么查

确认原始请求体的顶层prompt是非空字符串，使用JSON UTF-8或正确multipart文本字段。
检查Content-Type与实际body一致，multipart的boundary不能丢失。
检查多层代理或SDK是否把字段改成messages/input，或者把POST转发成了空body。
参考图必须是完整可读取的图片地址；https:///...、省略号、需登录页面、仅文件路径都无效。
仍失败时提供本站request_id、时间、完整型号、去除Key与私有素材的请求结构，保留原任务核查。

不要因为错误提到prompt就删除参考图改成纯文生图。也不要把第三方工具的“转换成官方格式”提示当成所有分组必须改格式；优先使用本站已说明的请求结构。