GPT Image 2

通过 qiuqiutoken 调用 gpt-image-2 时，按本页准备图片生成和图片编辑请求。站内模型名继续填写 gpt-image-2；字段完整定义、模型限定和最新可选值以 OpenAI 官方接口文档为准。

开始前，先在快速开始准备余额，再到创建 API 令牌创建图片分组令牌。

生成图片：`POST /v1/images/generations`

官方资料

这一节只整理 qiuqiutoken 接入时常用的生成字段。完整字段、枚举值和返回结构以 OpenAI 官方文档为准：

最小可用请求如下：

curl

curl https://api.qiuqiutoken.com/v1/images/generations \
  -H "Authorization: Bearer 你的图片分组令牌key" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"gpt-image-2\",
    \"prompt\": \"一只戴透明雨衣的橘猫站在霓虹雨夜街头，电影感构图\",
    \"size\": \"1024x1024\",
    \"quality\": \"high\",
    \"output_format\": \"png\"
  }"

常用请求字段

字段	是否必填	说明
`prompt`	必填	图片提示词。建议直接写主体、场景、光线、构图、风格等关键信息。
`model`	推荐填写	在 qiuqiutoken 网关中填写 `gpt-image-2`。官方字段本身可选，但这里建议显式传入。
`size`	可选	输出尺寸。GPT Image 常见值包括 `1024x1024`、`1536x1024`、`1024x1536` 和 `auto`。
`quality`	可选	输出质量。GPT Image 常见值为 `low`、`medium`、`high`、`auto`；更高质量通常意味着更慢和更贵。
`background`	可选	背景模式。常见值为 `transparent`、`opaque`、`auto`；透明背景需要配合 `png` 或 `webp` 输出。
`output_format`	可选	输出格式。常见值为 `png`、`jpeg`、`webp`。
`output_compression`	可选	输出压缩率，官方范围为 `0` 到 `100`；只在 `jpeg` 或 `webp` 输出时有意义。
`n`	可选	生成张数。官方范围为 `1` 到 `10`。
`moderation`	可选	GPT Image 的审核强度。官方常见值为 `low` 和 `auto`。
`user`	可选	业务侧终端用户标识，便于审计、风控或日志关联。

易混字段

stream：官方 GPT Image 生成接口支持流式返回，默认是 false；实际是否可用以当前网关和上游能力为准。
partial_images：只在 stream=true 时有意义，官方范围为 0 到 3，用于控制流式中间图数量。
response_format：官方说明中用于 dall-e-2 / dall-e-3 在 url 与 b64_json 之间切换；GPT Image 模型不支持该参数，并始终按 Base64 图片处理。
style：官方说明中仅 dall-e-3 支持 vivid / natural；gpt-image-2 路径不要传这个字段。

响应与返回格式

对 GPT Image 系列模型，重点关注 data[*].b64_json。也就是说，最常见的返回不是图片 URL，而是 Base64 编码后的图片内容。

{
  "created": 1711111111,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ]
}

编辑图片：`POST /v1/images/edits`

官方资料

这一节只整理 qiuqiutoken 接入时常用的编辑字段。完整字段、输入图引用方式、蒙版规则和最新说明以 OpenAI 官方文档为准：

图片编辑推荐直接使用 multipart/form-data 上传原图、可选蒙版和文本提示词。OpenAI 官方参考页把输入图表示为 images 数组；使用 multipart 上传文件时，常见写法是 image[]=@...。

curl

curl https://api.qiuqiutoken.com/v1/images/edits \
  -H "Authorization: Bearer 你的图片分组令牌key" \
  -F "model=gpt-image-2" \
  -F "image[]=@./input.png" \
  -F "mask=@./mask.png" \
  -F "prompt=保留主体姿势，把背景改成雨夜霓虹街道，增强电影感和反射光" \
  -F "size=1024x1024" \
  -F "quality=high" \
  -F "background=transparent" \
  -F "input_fidelity=high" \
  -F "output_format=png" \
  -F "n=1"

常用请求字段

字段	是否必填	说明
`images` / `image[]`	必填	要编辑的输入图片。GPT Image 模型官方支持最多 16 张输入图；multipart 上传时通常使用 `image[]=@./input.png`。
`prompt`	必填	编辑意图说明。建议明确写出“保留什么、替换什么、补什么”，避免只写抽象风格词。
`model`	推荐填写	在 qiuqiutoken 网关中填写 `gpt-image-2`。官方字段本身可选，但这里建议显式传入。
`mask`	可选	蒙版。可通过文件上传或官方支持的引用方式提供；透明区域表示可编辑区域。
`size`	可选	输出尺寸。GPT Image 常见值包括 `1024x1024`、`1536x1024`、`1024x1536` 和 `auto`。
`quality`	可选	输出质量。GPT Image 常见值为 `low`、`medium`、`high`、`auto`。
`background`	可选	背景模式。常见值为 `transparent`、`opaque`、`auto`；透明背景需要配合 `png` 或 `webp` 输出。
`input_fidelity`	可选	控制对原图细节的保留强度。官方常见值为 `low` 和 `high`。
`output_format`	可选	输出格式。常见值为 `png`、`jpeg`、`webp`。
`output_compression`	可选	输出压缩率，官方范围为 `0` 到 `100`；只在 `jpeg` 或 `webp` 输出时有意义。
`n`	可选	返回图片数量。官方范围为 `1` 到 `10`。
`moderation`	可选	GPT Image 的审核强度。官方常见值为 `low` 和 `auto`。
`user`	可选	业务侧终端用户标识，便于审计、风控或日志关联。

易混字段

stream：官方 GPT Image 编辑接口支持流式事件返回，默认是 false；实际是否可用以当前网关和上游能力为准。
partial_images：只在 stream=true 时有意义，官方范围为 0 到 3，用于控制流式中间图数量。
response_format：官方编辑接口当前没有把它列为请求字段；按 GPT Image 路径处理时，不要把它当作稳定 URL 返回开关。
mask：使用蒙版时要保证尺寸和输入图匹配；透明区域表示需要编辑的部分。

官方约束要点

images / image[] 和 mask 都是输入图相关字段，不是普通 JSON 文本字段。
GPT Image 模型最多可提供 16 张输入图；过多图片或过大文件会导致参数错误。
output_compression 只有在 jpeg 或 webp 时才有意义；如果需要透明背景，优先用 png 或 webp。
input_fidelity、stream、partial_images 等字段的最终可用性取决于当前上游模型和网关透传能力。

如何落盘保存

无论是生成还是编辑，只要响应里拿到的是 b64_json，都需要先解码再保存成图片文件。

python - <<'PY'
import base64

b64 = "把响应里的 b64_json 粘贴到这里"
with open("gpt-image-output.png", "wb") as f:
    f.write(base64.b64decode(b64))
PY

如果你在生成或编辑时使用了 background=transparent，保存文件时也应优先选择 png 或 webp，否则透明信息可能丢失。

常见报错排查

返回 401 或认证失败：确认使用的是 Authorization: Bearer，并且令牌来自正确图片分组，不是 default。
返回 404：确认请求地址分别是 https://api.qiuqiutoken.com/v1/images/generations 或 https://api.qiuqiutoken.com/v1/images/edits，同时模型名填写为 gpt-image-2。
生成接口提示参数错误：先缩回最小 JSON 示例，只保留 model、prompt 和一个已验证可用的 size，再逐个加回其他字段。
编辑接口提示文件字段错误：确认 image[] 和 mask 是 multipart/form-data 文件上传或官方支持的图片引用方式，而不是普通 JSON 文本。
结果无法直接打开：检查你保存的是解码后的二进制图片，而不是原始 Base64 字符串。
透明背景没有生效：确认使用了 background=transparent，并把 output_format 设为 png 或 webp。