功能与模型

适合商品图、插画、海报素材和场景创作。描述主体、构图、色彩、文字内容与风格，不传 image。5.0 Lite、4.5、4.0均支持单图生成，尺寸档位和图片编码见参数与模型限制。

第一步：设置鉴权

使用请求头 Authorization: Bearer YOUR_API_KEY。把 YOUR_API_KEY 替换为青云TOP API 的 API Key，保留 Bearer 后一个空格。

第二步：调用模型

向 https://top.qingyuntop.ai/v1/images/generations 发送 POST，使用 Content-Type: application/json。默认等待 JSON 返回；不需要创建任务后再查询。

请求参数

字段与类型填写规则、默认值与限制
model；string必填；JSON 顶层。使用本目录模型表的完整 ID，没有推荐默认型号。5.0 Lite 的本站 ID 不带 lite 后缀。
prompt；string必填；JSON 顶层非空文本。说明主体、构图、风格和需要保留或修改的部分；多图可按数组顺序称图1、图2。支持中英文，建议中文不超过300字、英文不超过600词；这是写作建议，不是硬性长度上限。
size；string可选；JSON 顶层。默认2048x2048。填模型允许的分辨率档位或宽x高字符串；两种方式选一种。像素值用 ASCII x，同时满足下表的总像素和宽高比限制。
response_format；string可选；JSON 顶层。url 返回临时图片链接；b64_json 返回图片的纯 Base64 字符串。只改变返回方式，不改变图片编码。 默认 url。
output_format；string可选；JSON 顶层。仅本目录的5.0 Lite可设 png 或 jpeg。4.5、4.0输出JPEG，请省略此字段。请求PNG不等于支持透明背景。 默认 jpeg。
watermark；boolean可选；JSON 顶层布尔值。true 在右下角添加可见的“AI生成”水印，false 关闭该可见水印；不代表清除所有隐式标记。不要传字符串。 默认 true。

代码示例：返回 PNG 链接

cURL示例使用Bash，需cURL 7.76+与jq；Python需3.10+并安装requests；Node.js需20+，保存为.mjs运行。600秒是示例的客户端超时设置，不是生成耗时承诺；Python的timeout分别控制连接和单次读取等待。代码会覆盖同名request.json或response.json，请按需另存。

set -euo pipefail
cat > request.json <<'JSON'
{
  "model": "doubao-seedream-5-0-260128",
  "prompt": "生成一张横向产品摄影：白色陶瓷咖啡杯放在浅木桌面上，清晨侧光，背景简洁，无文字。",
  "size": "2K",
  "response_format": "url",
  "output_format": "png",
  "watermark": true
}
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" \
  --data-binary @request.json --output response.json
jq -e 'if .error then error(.error | tostring) else
  (.data | type == "array" and length > 0) and
  all(.data[]; (.error | not) and (.url | type == "string" and length > 0)) end' response.json

代码示例：返回 JPEG Base64

此例使用4.5的明确正方形尺寸，省略该型号不支持的 output_format，返回的 b64_json 解码后是JPEG。两组示例各发起一次独立生成，按业务需求选择一组即可。

set -euo pipefail
cat > request.json <<'JSON'
{
  "model": "doubao-seedream-4-5-251128",
  "prompt": "生成一张正方形插画：雨后的小巷，一只橘猫坐在窗台上，暖色灯光，细腻水彩风格。",
  "size": "2048x2048",
  "response_format": "b64_json",
  "watermark": true
}
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" \
  --data-binary @request.json --output response.json
jq -e 'if .error then error(.error | tostring) else
  (.data | type == "array" and length > 0) and
  all(.data[]; (.error | not) and (.b64_json | type == "string" and length > 0)) end' response.json

响应与图片保存

示例将 JSON 保存为 response.json，还没有把图片保存到本地。URL 返回读 data[0].url，Base64 返回读 data[0].b64_json；完整字段表和可直接衔接的三语言保存代码见返回结果与图片保存。

HTTP成功但有 error、图片项含 error 或没有图片数据时，不要显示“生成完成”。临时下载链接应尽快保存，切勿作为永久业务地址。

常见错误与参考

尺寸不支持时先改为当前模型允许的 2K；4.5和4.0不传 output_format。不要用 n 试图生成组图，也不要把 /api/v3 厂商路径追加到本站域名。更多排查见常见错误。参考：官方图像生成 API。