POST/v1/images/edits

GPT Image 图片编辑与多图输入

通过 multipart 文件上传提交一张或多张参考图片，让 GPT Image 修改背景、转换风格或结合参考图生成新的图片。

API Key multipart/form-data

功能、模型与素材

支持 GPT Image 2.5 Sunburst、2.5 Flare、2、1.5 和 1。输入 1–16 张 PNG、JPEG 或 WebP，每张小于 50 MB；总请求还受上传限制。示例使用两张本地 PNG：第一张 input.png 为主图，第二张 reference.png 为配色参考。请换成你的实际文件。

图片编辑不是像素级的无损修改。希望尽量保留主体特征时，使用 input_fidelity=high 并在 prompt 中明确需要保留的部分。指定局部区域请使用蒙版编辑。

第一步：设置鉴权

请求头使用 Authorization: Bearer YOUR_API_KEY。将 YOUR_API_KEY 替换为青云TOP API 的 API Key，保留 Bearer 后的一个空格。基础地址为 https://top.qingyuntop.ai；使用 SDK 时，base_url 通常填写 https://top.qingyuntop.ai/v1。

第二步：上传并调用模型

发送 POST https://top.qingyuntop.ai/v1/images/edits，请求为 multipart/form-data。让客户端自动生成 Content-Type 和 boundary；不要手写 JSON Content-Type 或不带 boundary 的表单 Content-Type。

Images API 兼容协议

调用与返回说明

使用青云TOP API 的 Images 兼容入口生成或编辑图片。它复用 OpenAI Images 的请求形状，但页面中的厂商型号、别名和能力仍需按本站当前模型目录核对。

请求时注意

请求头使用 Authorization: Bearer YOUR_API_KEY 和页面声明的 Content-Type。路径中的厂商名称不改变青云TOP API 的鉴权方式，也不要求客户端携带厂商密钥。
模型 ID、模型版本和后缀必须使用当前账号 GET /v1/models 返回且与本页协议匹配的值；旧示例中的固定型号不能视为永久可用。
生成接口通常将 prompt、model、size/比例和输出格式放在 JSON Body；编辑接口还要按 schema 传入 image、mask 或多图素材。不要把 multipart 字段拼进 JSON。
如果请求包含图片 URL、Base64 或文件，先核对页面中的媒体类型、大小和数组顺序；上游支持某种素材不代表本站所有渠道都开放。

返回时注意

同步图片响应通常在 data、output 或等价字段中返回 URL、Base64 或图片对象；先检查 HTTP 状态和错误字段，再按返回格式保存结果。
URL 可能有有效期，Base64 需要按响应中的格式解码。不要把示例 URL 当作永久存储地址，也不要把 Markdown 预览当作二进制文件。

Request

请求

/v1/images/edits

Body

必填

Bodyobject

imagestring必填

要编辑的图片。必须是受支持的图片文件或图片数组。对于 gpt-image-1，每张图片应为小于 25MB 的 png、webp 或 jpg 文件。对于 dall-e-2，您只能提供一张图片，并且该图片应为小于 4MB 的方形 png 文件。

示例

promptstring必填

所需图像的文本描述。dall-e-2 的最大长度为 1000 个字符，gpt-image-1 的最大长度为 32000 个字符。

示例将他们合并在一个图片里面

maskstring必填

一张附加图片，其完全透明区域（例如，alpha 值为零）指示应编辑 image 位置。如果提供了多张图片，则遮罩将应用于第一张图片。必须是有效的 PNG 文件，小于 4MB，且尺寸与 image 相同。

示例

modelstring必填

用于生成图像的模型。仅支持 dall-e-2 和 gpt-image-1。除非使用特定于 gpt-image-1 参数，否则默认为 dall-e-2。

示例gpt-image-1

ninteger必填

要生成的图像数量。必须介于 1 到 10 之间。

示例1

qualitystring必填

生成图像的质量。只有 gpt-image-1 支持 high、medium 和 low 质量。dall-e-2 仅支持 standard 质量。默认为 auto。

示例

response_formatstring必填

返回生成图像的格式。必须是 url 或 b64_json 之一。URL 在图像生成后 60 分钟内有效。此参数仅适用于 dall-e-2，因为 gpt-image-1 始终返回 base64 编码的图像。

示例b64_json

sizestring必填

生成图像的尺寸。对于 gpt-image-1，必须为 1024x1024、1536x1024（横向）、1024x1536（纵向）或 auto（默认值）之一；对于 dall-e-2，必须为 256x256、512x512 或 1024x1024 之一。

示例1024x1536

backgroundstring

允许为生成的图像的背景设置透明度。此参数仅在 gpt-image-1 中受支持。其值必须为 “透明（transparent）”、“不透明（opaque）” 或 “自动（auto）”（默认值）之一。当使用 “自动（auto）” 时，模型将自动为图像确定最佳背景。

示例transparent

moderationstring

控制由 gpt-image-1 生成的图像的内容审核级别。可以设置为 “low” 以进行限制较少的过滤，也可以设置为 “auto”（默认值）。

示例low

路径、查询与 Header 参数

参数	位置	类型	必填	说明	示例
`Accept`	Header	string	是	-	application/json
`Authorization`	Header	string	是	必填。使用青云TOP API 的 API Key，保留 Bearer 后的空格。	Bearer YOUR_API_KEY

请求示例multipart/form-data

curl --fail-with-body --connect-timeout 30 --max-time 600 "https://top.qingyuntop.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --form-string 'model=gpt-image-2.5-sunburst' \
  --form-string 'prompt=以第一张图为主图，参考第二张图的配色，把主图背景改为暖色书房，保留主图主体的外观。' \
  --form-string 'n=1' \
  --form-string 'size=1024x1024' \
  --form-string 'quality=high' \
  --form-string 'input_fidelity=high' \
  --form-string 'output_format=png' \
  -F 'image[]=@input.png;type=image/png' \
  -F 'image[]=@reference.png;type=image/png' \
  --output response.json

Response

返回响应 `200`

HTTP 响应

响应 200object

idstring必填

objectstring必填

createdinteger必填

choicesarray<object>必填

元素object

indexinteger

messageobject

rolestring必填

contentstring必填

finish_reasonstring

usageobject必填

prompt_tokensinteger必填

completion_tokensinteger必填

total_tokensinteger必填

响应示例json

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "\n\nHello there, how may I assist you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21
  }
}

Images API 兼容协议

调用与返回说明

使用青云TOP API 的 Images 兼容入口生成或编辑图片。它复用 OpenAI Images 的请求形状，但页面中的厂商型号、别名和能力仍需按本站当前模型目录核对。

请求时注意

请求头使用 Authorization: Bearer YOUR_API_KEY 和页面声明的 Content-Type。路径中的厂商名称不改变青云TOP API 的鉴权方式，也不要求客户端携带厂商密钥。
模型 ID、模型版本和后缀必须使用当前账号 GET /v1/models 返回且与本页协议匹配的值；旧示例中的固定型号不能视为永久可用。
生成接口通常将 prompt、model、size/比例和输出格式放在 JSON Body；编辑接口还要按 schema 传入 image、mask 或多图素材。不要把 multipart 字段拼进 JSON。
如果请求包含图片 URL、Base64 或文件，先核对页面中的媒体类型、大小和数组顺序；上游支持某种素材不代表本站所有渠道都开放。

返回时注意

同步图片响应通常在 data、output 或等价字段中返回 URL、Base64 或图片对象；先检查 HTTP 状态和错误字段，再按返回格式保存结果。
URL 可能有有效期，Base64 需要按响应中的格式解码。不要把示例 URL 当作永久存储地址，也不要把 Markdown 预览当作二进制文件。

多图编辑示例

点击横向标签切换语言。cURL 示例使用 Bash，需支持 --fail-with-body；Python 需安装 requests；Node.js 需 20 或更新版本，保存为 .mjs。示例超时设为 600 秒，是客户端设置，不是生成时限承诺。Python/Node.js 将结果保存为 output-1.png 等文件；cURL 保存为 response.json，按结果保存解码。

curl --fail-with-body --connect-timeout 30 --max-time 600 "https://top.qingyuntop.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --form-string 'model=gpt-image-2.5-sunburst' \
  --form-string 'prompt=以第一张图为主图，参考第二张图的配色，把主图背景改为暖色书房，保留主图主体的外观。' \
  --form-string 'n=1' \
  --form-string 'size=1024x1024' \
  --form-string 'quality=high' \
  --form-string 'input_fidelity=high' \
  --form-string 'output_format=png' \
  -F 'image[]=@input.png;type=image/png' \
  -F 'image[]=@reference.png;type=image/png' \
  --output response.json

只上传一张时，删除第二个文件项，并把剩余项的字段改成 image；同时把 prompt 改为针对单张图的修改要求。修改模型时使用完整 ID，并同步检查质量档位。

响应与图片保存

普通响应通过 data[].b64_json 返回最终图片，处理方式与文生图相同；Python/Node.js 示例已经保存图片。字段说明见返回结果与图片保存。

要流式编辑，在表单中增加 stream=true 和 partial_images=2，保持文件字段不变，再按流式事件说明消费响应；不要对 SSE 使用 response.json()。

常见错误与参考

缺少图片时检查是否真正上传二进制文件；413 时检查每张大小、图片总量及请求总体积，优先压缩素材或分次处理；格式错误时检查文件真实编码与扩展名是否一致。不要把文件改名当作格式转换。

官方参考：OpenAI Images 编辑参数，相关说明：参数与模型限制。

GPT Image 图片编辑与多图输入

功能、模型与素材

第一步：设置鉴权

第二步：上传并调用模型

调用与返回说明

请求时注意

返回时注意

请求

Body

路径、查询与 Header 参数

返回响应 200

调用与返回说明

请求时注意

返回时注意

多图编辑示例

响应与图片保存

常见错误与参考

返回响应 `200`