POST/v1/images/edits

GPT Image JSON 图片编辑

将公开图片 URL 或 Base64 Data URL 放入 JSON 的 images 数组，调用 GPT Image 编辑图片，无需构造文件表单。

API Key multipart/form-data

功能、模型与输入

本页适用于 gpt-image-2.5-sunburst、gpt-image-2.5-flare、gpt-image-2、gpt-image-1.5 和 gpt-image-1。输入 1–16 张 PNG、JPEG 或 WebP，每张小于 50 MB，图片顺序按数组顺序保留。

公开 URL 必须能被服务端访问，不能指向本机文件、局域网地址或需要浏览器登录的页面。Data URL 形式为 data:image/png;base64, 后接真实文件的 Base64 内容；不能只放裸 Base64。编码会增大请求体，较大的本地图片优先用文件上传。

第一步：设置鉴权

请求头使用 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，设置 Content-Type: application/json。

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.5

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 编码的图像。

示例url

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" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2.5-flare",
  "prompt": "保留画面主体和构图，将图片变为柔和的水彩风格。",
  "images": [
    {
      "image_url": "https://example.com/input.png"
    }
  ],
  "n": 1,
  "size": "1024x1024",
  "quality": "medium",
  "output_format": "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 预览当作二进制文件。

JSON 编辑示例

示例中的 https://example.com/input.png 是需要替换的占位地址，不能直接用于生成。请先替换为你自己的可公开访问 PNG/JPEG/WebP URL，或完整 Data URL。三种语言使用同一请求内容。

点击横向标签切换语言。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" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2.5-flare",
  "prompt": "保留画面主体和构图，将图片变为柔和的水彩风格。",
  "images": [
    {
      "image_url": "https://example.com/input.png"
    }
  ],
  "n": 1,
  "size": "1024x1024",
  "quality": "medium",
  "output_format": "png"
}' \
  --output response.json

常见错误与参考

图片获取失败时，先检查 URL 返回的确实是图片而不是 HTML、登录页或失效链接；可换成 Data URL 或本地上传。字段错误时检查 images 是否为对象数组，图片引用是否放在 image_url 下。

官方参考：OpenAI JSON 图片编辑定义。

GPT Image JSON 图片编辑

功能、模型与输入

第一步：设置鉴权

第二步：调用模型

调用与返回说明

请求时注意

返回时注意

请求

Body

路径、查询与 Header 参数

返回响应 200

调用与返回说明

请求时注意

返回时注意

JSON 编辑示例

常见错误与参考

返回响应 `200`