POST/v1/images/edits

GPT Image 蒙版局部编辑

向编辑接口同时上传原图和带透明通道的 PNG 蒙版，指定希望修改的区域，适合替换物体、调整背景和局部重绘。

API Key multipart/form-data

功能、模型与蒙版规则

支持 GPT Image 2.5 Sunburst、2.5 Flare、2、1.5 和 1。蒙版是编辑区域提示，不是像素级的锁定保证；请在 prompt 中同时描述修改区域与要保留的主体。

原图可为 PNG、JPEG 或 WebP，小于 50 MB。蒙版必须为 PNG、小于 4 MB，宽高与原图完全相同，并带 alpha 通道。alpha 为 0 的完全透明区域表示需要修改，其他区域表示希望保留；一张普通黑白图并不等价于透明蒙版。不要把这些规则与输出参数 background=transparent 混淆。

上传多张图片时，蒙版只应用于第一张，所有输入总数不超过 16。本例只上传 input.png 和 mask.png；这两个文件名都需要换成你的实际文件。

第一步：设置鉴权

请求头使用 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。客户端自动生成 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 文件。

示例file://C:\Users\Administrator\Desktop\sunlit_lounge.png

promptstring必填

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

示例A sunlit indoor lounge area with a pool containing a flamingo

maskstring必填

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

示例file://C:\Users\Administrator\Desktop\mask.png

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 之一。

示例1024x1024

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' \
  --form-string 'prompt=把蒙版透明区域内的物体替换为一盆绿色植物，尽量保持其余构图、光线和主体一致。' \
  --form-string 'n=1' \
  --form-string 'size=1024x1024' \
  --form-string 'quality=high' \
  --form-string 'output_format=png' \
  -F 'image=@input.png;type=image/png' \
  -F 'mask=@mask.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' \
  --form-string 'prompt=把蒙版透明区域内的物体替换为一盆绿色植物，尽量保持其余构图、光线和主体一致。' \
  --form-string 'n=1' \
  --form-string 'size=1024x1024' \
  --form-string 'quality=high' \
  --form-string 'output_format=png' \
  -F 'image=@input.png;type=image/png' \
  -F 'mask=@mask.png;type=image/png' \
  --output response.json

响应与效果检查

结果通过 data[].b64_json 返回，示例会保存最终 PNG。检查局部修改是否满足需求，同时检查蒙版外的主体、文字和构图；需要严格像素不变的场景，应在应用中对原图和生成图进行后续合成。

JSON 方式的蒙版应放在 mask.image_url，输入图片放在 images[].image_url。具体字段见JSON 图片编辑，不要把 multipart 的文件字段直接放入 JSON。

常见错误与参考

蒙版无效时检查真实 PNG 编码、alpha 通道、体积和宽高；作用区域错误时检查透明区域是否画反，主图是否位于第一张。更多响应与超时处理见结果说明。

官方参考：OpenAI Images 蒙版定义。

GPT Image 蒙版局部编辑

功能、模型与蒙版规则

第一步：设置鉴权

第二步：提交原图与蒙版

调用与返回说明

请求时注意

返回时注意

请求

Body

路径、查询与 Header 参数

返回响应 200

调用与返回说明

请求时注意

返回时注意

蒙版编辑示例

响应与效果检查

常见错误与参考

返回响应 `200`