青云TOP API使用教程&开发文档小白用户&专业开发者快速使用指南
控制台
返回模型调用 API 参考
POST/v1/images/generations

GPT Image 文生图

向 Images 生成接口提交文字提示，使用 GPT Image 2.5 或 2 等模型生成一张或多张图片，并保存为 PNG、JPEG 或 WebP。

API Key application/json

功能与支持模型

适合海报、插画、产品概念图和透明背景素材。不需要上传参考图片；需要保留已有主体时使用图片编辑。本页支持模型为 gpt-image-2.5-sunburst、gpt-image-2.5-flare、gpt-image-2、gpt-image-1.5 和 gpt-image-1。

默认示例选用 2.5 Flare，1024x1024、medium、PNG、1 张；自定义横图示例使用 2；透明素材示例使用 2.5 Sunburst。质量和尺寸不能跨型号任意复制，完整组合见参数与模型限制。

第一步：设置鉴权

请求头使用 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/generations，请求头设置 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/generations

Body

必填
Bodyapplication/json
Bodyobject
promptstring必填

所需图像的文本描述。最大长度为 1000 个字符。

ninteger必填

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

sizestring必填

生成图像的尺寸。对于 GPT 图像模型，必须是 1024x1024 、 1536x1024 （横版）、 1024x1536 （竖版）或 auto （默认值）之一，对于 dall-e-2 必须是 256x256 、 512x512 或 1024x1024 之一，对于 dall-e-3 必须是 1024x1024 、 1792x1024 或 1024x1792 之一。

路径、查询与 Header 参数

参数位置类型必填说明示例
Content-TypeHeaderstring是-application/json
AcceptHeaderstring是-application/json
AuthorizationHeaderstring是必填。使用青云TOP API 的 API Key，保留 Bearer 后的空格。Bearer YOUR_API_KEY
Response

返回响应 200

HTTP 响应
响应 200json
响应 200object
idstring必填
objectstring必填
createdinteger必填
choicesarray<object>必填
元素object
indexinteger
messageobject
rolestring必填
contentstring必填
finish_reasonstring
usageobject必填
prompt_tokensinteger必填
completion_tokensinteger必填
total_tokensinteger必填
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 预览当作二进制文件。

GPT Image 2.5 Flare：方形海报

点击横向标签切换语言。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/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2.5-flare",
  "prompt": "为一家书店设计方形海报，米白背景，画面中是一只正在读书的橘猫，顶部写清晰的中文标题：周末读书会。",
  "n": 1,
  "size": "1024x1024",
  "quality": "medium",
  "output_format": "png"
}' \
  --output response.json

GPT Image 2：自定义横图与 JPEG 压缩

本例的 1536x864 宽高都是 16 的倍数，比例为 16:9；使用 output_format=jpeg 时设置不透明背景，压缩参数为 85。保存的文件后缀为 .jpeg。

curl --fail-with-body --connect-timeout 30 --max-time 600 "https://top.qingyuntop.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2",
  "prompt": "黄昏海边的灯塔，横向构图，水彩插画，无文字。",
  "n": 1,
  "size": "1536x864",
  "quality": "medium",
  "output_format": "jpeg",
  "output_compression": 85,
  "background": "opaque"
}' \
  --output response.json

GPT Image 2.5 Sunburst：透明背景素材

使用 background=transparent、output_format=png 和 2.5 支持的 xhigh。若切换到 2、1.5 或 1，需要将 quality 改为 high、medium、low 或 auto；2 的透明背景仍处于预览阶段。

curl --fail-with-body --connect-timeout 30 --max-time 600 "https://top.qingyuntop.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "一只可爱的橘猫贴纸，主体完整，透明背景，无阴影，无文字。",
  "n": 1,
  "size": "1024x1024",
  "quality": "xhigh",
  "background": "transparent",
  "output_format": "png"
}' \
  --output response.json

常见错误与参考

invalid model 先检查是否写成了 gpt-image-2.5 或未经确认的别名；质量错误检查是否把 2.5 的 xhigh/max 发给了 2；透明背景错误检查是否仍在输出 JPEG。401、429 和超时的处理见常见错误。

官方参考：OpenAI Images API 定义。