Images API
文生图、multipart 参考图与图片保存
接口与请求体
| 操作 | 路径 | 编码 |
|---|---|---|
| 文生图 | POST /v1/images/generations | application/json |
| gpt-image-2 参考图编辑 | POST /v1/images/edits | multipart/form-data |
| gpt-image-2.5-flare / gpt-image-2.5-sunburst 参考图编辑 | POST /v1/images/edits?api-version=2025-04-01-preview | multipart/form-data |
使用 Authorization: Bearer <API_KEY> 鉴权。编辑接口需上传图片文件内容；multipart 的 Content-Type 和 boundary 由 HTTP 库生成，无需手动设置。
生成字段
| 字段 | gpt-image-2 | gpt-image-2.5-flare / gpt-image-2.5-sunburst |
|---|---|---|
| model | 完整 ID，含命名空间 | 完整 ID，含型号后缀 |
| prompt | 文本描述或编辑指令 | 文本描述或编辑指令 |
| size | auto 或 WIDTHxHEIGHT | auto 或 WIDTHxHEIGHT |
| quality | auto、low、medium、high | auto、low、medium、high、xhigh、max |
| output_format | png、jpeg | png、jpeg |
| output_compression | 0–100，仅 jpeg | 0–100，仅 jpeg |
| background | auto、opaque | auto、opaque、transparent；透明输出用 png |
| moderation | auto、low | auto、low |
| n | 1–10，结果逐项读取 data 数组 | 1–10，结果逐项读取 data 数组 |
| response_format | 不发送，解析 b64_json | 不发送，解析 b64_json |
| input_fidelity | 不发送 | 不发送 |
quality 设置生成质量，size 设置像素尺寸。质量档位不能仅凭 HTTP 状态、字段回显、文件体积或观感判断。请保存请求参数和返回元数据，图片大小也不能用来计算费用。
{
"model": "gpt-image-2",
"prompt": "白色桌面上一个蓝色陶瓷杯，正面产品摄影，无文字",
"size": "1024x1024",
"quality": "medium",
"output_format": "png",
"n": 1
}尺寸约束
size 使用小写 x，例如 1024x1024、1536x1024、1024x1536。自定义尺寸需符合型号要求。gpt-image-2 的宽高须为 16 的倍数，长短边比例不超过 3，最长边不超过 3840，总像素为 655360–8294400。
auto 的输出宽高由服务决定，可能为非正方形。排版、存储和制作蒙版时，请读取解码后的图片尺寸。本接口不使用 resolution、aspectRatio 或 Chat 的 messages。
单图、多图和蒙版
单张参考图使用 image，多张则重复使用 image[] 文件字段，并在提示词中按上传顺序说明图 1、图 2 的用途。支持 PNG、JPEG、WebP；gpt-image-2 可传 1–16 张，每张小于 50 MB。总请求大小还需计入 multipart 开销，并符合网关限制。
mask 为带 Alpha 通道的 PNG，与第一张参考图宽高一致，透明区域表示主要编辑区域。蒙版作用于第一张参考图，其余图片是辅助参考。生成式编辑不保证蒙版外逐像素不变。
curl --fail-with-body --max-time 300 \
'https://www.yunqiai.chat/v1/images/edits?api-version=2025-04-01-preview' \
-H "Authorization: Bearer $YUNQIAI_API_KEY" \
-F 'model=gpt-image-2.5-flare' \
-F 'image[]=@scene.png;type=image/png' \
-F 'image[]=@product.png;type=image/png' \
-F 'prompt=保留图1的场景，将图2的商品放在桌面中央，保持商品轮廓和颜色' \
-F 'size=1024x1024' -F 'quality=medium' -F 'n=1'参考图通过独立文件字段提交，prompt 只填写编辑指令。其他协议可能用 Base64 编码图片，但都需放在相应的图片字段中；将 Base64 或 URL 当作普通提示词文字发送，无法代替此处的文件上传。
保存图片
完整程序见 images.py，支持 generate / edit、多参考图和 mask。程序逐张解码图片，检查格式及尺寸后按对应后缀保存；转换格式需实际转码，不能只改后缀。
先检查 HTTP 状态和错误正文，再确认 data[] 非空、每张图片可解码且实际尺寸符合请求。指定 size 与返回宽高不符时，保留原图并报告校验错误，不直接拉伸。返回 URL 时请及时下载，下载请求无需向第三方图片域名发送 YunQi Key；签名链接不宜用作永久存储。
images.py --timeout 600 将客户端读取超时设为 600 秒，不改变服务端执行时限。程序发送前校验数量、尺寸格式和质量取值，返回后校验图片格式、尺寸和张数。客户端超时后，服务端可能仍在生成，请先确认状态再重发。
Images 用于生成和编辑图片。图片理解使用 Chat / Responses / Messages / Gemini 的内容块，不使用这里的 prompt、mask 字段。
参数定义可参考 OpenAI Images 和 Microsoft Foundry 图像接口。调用 YunQi 时，地址、Key 和模型 ID 使用本站配置，无需 Azure 资源域名、deployment 路径或上游密钥。