端点 POST /v1/images/edits
与 OpenAI Images API 兼容，以 multipart/form-data 上传原图并给出修改指令。耗时与生成图像相当，客户端超时建议设为 300 秒。
请求
content-type 为 multipart/form-data，鉴权用 Authorization: Bearer sk-xxxxxx。
参数
| 表单字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | gpt-image-2 |
image | 文件 | 是 | 原图 |
prompt | string | 是 | 修改指令 |
mask | 文件 | 否 | 遮罩图，透明区域为可编辑区域，尺寸与原图一致 |
n | integer | 否 | 生成张数，默认 1 |
size | string | 否 | 输出尺寸 宽x高，如 1024x1024；或 auto |
quality | string | 否 | low、medium、high 或 auto |
background | string | 否 | transparent、opaque 或 auto |
input_fidelity | string | 否 | 对原图细节的保真程度，high 或 low |
output_format | string | 否 | png（默认）、jpeg 或 webp |
output_compression | integer | 否 | 0 到 100，仅对 jpeg 与 webp 生效 |
stream | boolean | 否 | 设为 true 时以 SSE 流式返回。事件格式取决于上游渠道：多数情况与 生成图像 相同（image.generation.chunk … image.generation.result，以 [DONE] 结束）；也可能是 OpenAI 原生事件，以 event: image_generation.completed 结束，结果图在该事件的 b64_json 里 |
partial_images | integer | 否 | 0 到 3 |
user | string | 否 | 调用方自定义的最终用户标识，原样透传 |
其余字段按 OpenAI Images API 格式透传。
响应
json
{
"created": 1752345600,
"data": [ { "b64_json": "iVBORw0KGgo..." } ],
"size": "1024x1024",
"quality": "…",
"output_format": "png",
"background": "…",
"moderation": "…",
"usage": { "…": "…" }
}| 字段 | 说明 |
|---|---|
data[].b64_json | Base64 编码的结果图 |
size / quality / output_format / background / moderation | 本次实际生效的输出设置 |
usage | 本次请求的用量 |
created 与 data[].b64_json 每次都返回；size、quality、output_format、background、moderation、usage 是否出现取决于本次调用的上游渠道，客户端按可选字段处理。实测 background 为 transparent 时，编辑接口返回的图片不带透明通道。
示例
bash
curl https://caapi.top/v1/images/edits \
-H "Authorization: Bearer sk-xxxxxx" \
-F model="gpt-image-2" \
-F image="@photo.png" \
-F prompt="把背景换成星空"错误
| HTTP 状态 | error.type | 触发条件 |
|---|---|---|
| 401 | missing_auth_credential / invalid_api_key / invalid_bearer_token | 鉴权失败，详见 鉴权 |