OpenAI 图像格式（Image）

官方文档

📝 简介

给定文本提示和/或输入图片，模型将生成新的图片。OpenAI 提供多种强大的图像生成模型，可以根据自然语言描述创建、编辑和修改图像。

🤖 支持的模型

目前支持的模型包括：

模型	描述
gpt-image-1	GPT-Image-1 图像生成模型
gpt-image-1.5	GPT-Image-1.5 图像生成和编辑模型
gpt-image-2	GPT-Image-2 图像生成和编辑模型，支持多图片编辑功能，能够基于多个输入图像创建新的组合图像
gpt-image-2.5-sunburst	功能最强大的 GPT-Image-2.5 模型，针对精确的图像生成和编辑进行了优化。同时支持日期快照 `gpt-image-2.5-sunburst-2026-09-08`。
gpt-image-2.5-flare	快速的 GPT-Image-2.5 模型，适用于高质量的日常图像生成和编辑。同时支持日期快照 `gpt-image-2.5-flare-2026-09-08`。

💡 请求示例

创建图片 ✅

# 生成图片并返回临时 URL
curl https://www.unodetech.xyz/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只可爱的小海獭",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'

# 最高质量的 GPT Image 2.5 图片生成
curl https://www.unodetech.xyz/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "一只可爱的小海獭",
    "quality": "max",
    "size": "1024x1024"
  }'

# 透明背景与 WebP 输出
curl https://www.unodetech.xyz/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只可爱的小海獭",
    "background": "transparent",
    "output_format": "webp"
  }'

响应示例:

{
  "created": 1589478378,
  "data": [
    {
      "url": "https://cdn.example.com/generated-images/...?...",
      "revised_prompt": "一只可爱的小海獭在水中嬉戏,它有着圆圆的眼睛和毛茸茸的皮毛"
    }
  ],
  "background": "opaque",
  "output_format": "png",
  "quality": "high",
  "size": "1024x1024",
  "usage": {
    "total_tokens": 100,
    "input_tokens": 50,
    "output_tokens": 50,
    "input_tokens_details": {
      "text_tokens": 10,
      "image_tokens": 40
    }
  }
}

编辑图片 ✅

# GPT Image 2.5 图片编辑
curl https://www.unodetech.xyz/v1/images/edits \
  -H "Authorization: Bearer $API_KEY" \
  -F image="@otter.png" \
  -F mask="@mask.png" \
  -F model="gpt-image-2.5-sunburst" \
  -F prompt="一只戴着贝雷帽的可爱小海獭" \
  -F size="1024x1024" \
  -F response_format="url"

# gpt-image-2 多图片编辑示例
curl https://www.unodetech.xyz/v1/images/edits \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=gpt-image-2" \
  -F "image[]=@body-lotion.png" \
  -F "image[]=@bath-bomb.png" \
  -F "image[]=@incense-kit.png" \
  -F "image[]=@soap.png" \
  -F "prompt=创建一个包含这四个物品的精美礼品篮" \
  -F "quality=high"

响应示例:

{
  "created": 1713833628,
  "data": [
    {
      "url": "https://cdn.example.com/generated-images/...?..."
    }
  ],
  "usage": {
    "total_tokens": 100,
    "input_tokens": 50,
    "output_tokens": 50,
    "input_tokens_details": {
      "text_tokens": 10,
      "image_tokens": 40
    }
  }
}

📮 请求

端点

创建图片

POST /v1/images/generations

根据文本提示创建图片。

编辑图片

POST /v1/images/edits

根据一个或多个原始图片和提示创建编辑或扩展的图片。

JSON 图片编辑请求

图片编辑同时支持 multipart/form-data 文件上传和 application/json 请求体。使用 JSON 请求时，请在 images 数组中提供源图片。每个图片引用必须包含 image_url（URL 或 Base64 数据 URL）或 file_id，遮罩也可以使用相同的引用格式。其他允许使用的编辑参数保持不变。

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "一只戴着贝雷帽的可爱小海獭",
  "images": [{ "image_url": "https://example.com/otter.png" }],
  "mask": { "file_id": "file-mask" },
  "quality": "max"
  // ...其他图片编辑参数
}

鉴权方法

在请求头中包含以下内容进行 API 密钥认证：

Authorization: Bearer $API_KEY

其中 $API_KEY 是您的 API 密钥。

请求体参数

创建图片 (`/v1/images/generations`)

参数	类型	必需	说明
`prompt`	字符串	是	期望生成图片的文本描述。最大长度为 32000 字符。
`model`	字符串	是	用于图像生成的模型，例如 `gpt-image-1`、`gpt-image-1.5`、`gpt-image-2`、`gpt-image-2.5-sunburst` 或 `gpt-image-2.5-flare`。同时支持以 `-2026-09-08` 结尾的 GPT Image 2.5 日期快照。
`n`	整数	否	要生成的图片数量（1–10）。默认值：`1`。
`size`	字符串	否	生成图片的尺寸。标准可选值：`1024x1024`、`1536x1024`（横版）、`1024x1536`（竖版）、`auto`。`gpt-image-2` 和两个 GPT Image 2.5 变体还支持自定义 `宽度x高度` 字符串；请参阅自定义尺寸。默认值：`auto`。
`quality`	字符串	否	GPT Image 模型的图像质量可选值为 `low`、`medium`、`high`、`auto`。GPT Image 2.5 Sunburst 和 Flare 还支持 `xhigh` 和 `max`。默认值：`auto`。
`background`	字符串	否	生成图片的背景。可选值：`transparent`、`opaque`、`auto`。透明背景要求 `output_format` 为 `png` 或 `webp`。默认值：`auto`。
`output_format`	字符串	否	返回图片的文件格式。可选值：`png`、`jpeg`、`webp`。默认值：`png`。
`output_compression`	整数	否	`jpeg` 与 `webp` 输出的压缩级别（0–100）。默认值：`100`。
`moderation`	字符串	否	生成图片的内容审核强度。可选值：`low`、`auto`。默认值：`auto`。
`response_format`	字符串	否	响应图片格式。`url` 请求图片 URL，`b64_json` 返回 Base64 数据。不传时保留模型或上游渠道的默认行为。
`stream`	布尔值	否	以流式模式生成图片。默认值：`false`。
`partial_images`	整数	否	流式响应中发送的部分图片数量（0–3）。仅在 `stream` 为 `true` 时有效。
`user`	字符串	否	代表最终用户的唯一标识符，可帮助 OpenAI 监控和检测滥用行为。

URL 响应

对于本身只返回 Base64 的 GPT Image 模型，API 会在 URL 交付功能可用时将生成结果保存到对象存储，并返回临时签名 URL。该参数由本 API 兼容层处理，不要求上游模型原生支持 response_format。

使用前需由平台管理员在当前环境启用图片 URL 交付，并确保当前 API 密钥或流量命中启用范围；否则 response_format=url 会返回 503。客户端无需配置或持有 Bunny 凭据。

编辑图片 (`/v1/images/edits`)

参数	类型	必需	说明
`image`	文件或文件数组	是	要编辑的图片。每个图片应为 PNG、WEBP 或 JPG 文件，小于 25MB。最多可提供 16 张图片作为数组。
`prompt`	字符串	是	期望编辑的文本描述。最大长度为 32000 字符。
`mask`	文件	否	额外的 PNG 图片，其完全透明区域（alpha 为零）指示应该编辑的位置。必须小于 4MB 且与 image 尺寸相同。
`model`	字符串	是	用于图像编辑的模型，例如 `gpt-image-1`、`gpt-image-1.5`、`gpt-image-2`、`gpt-image-2.5-sunburst` 或 `gpt-image-2.5-flare`。同时支持以 `-2026-09-08` 结尾的 GPT Image 2.5 日期快照。
`n`	整数	否	要生成的图片数量（1–10）。默认值：`1`。
`size`	字符串	否	生成图片的尺寸。标准可选值：`1024x1024`、`1536x1024`（横版）、`1024x1536`（竖版）、`auto`。`gpt-image-2` 和两个 GPT Image 2.5 变体还支持自定义 `宽度x高度` 字符串；请参阅自定义尺寸。默认值：`auto`。
`quality`	字符串	否	GPT Image 模型的图像质量可选值为 `low`、`medium`、`high`、`auto`。GPT Image 2.5 Sunburst 和 Flare 还支持 `xhigh` 和 `max`。默认值：`auto`。
`background`	字符串	否	生成图片的背景。可选值：`transparent`、`opaque`、`auto`。透明背景要求 `output_format` 为 `png` 或 `webp`。默认值：`auto`。
`output_format`	字符串	否	返回图片的文件格式。可选值：`png`、`jpeg`、`webp`。默认值：`png`。
`output_compression`	整数	否	`jpeg` 与 `webp` 输出的压缩级别（0–100）。默认值：`100`。
`input_fidelity`	字符串	否	控制输出与输入图片的契合程度。可选值：`high`、`low`。
`moderation`	字符串	否	生成图片的内容审核强度。可选值：`low`、`auto`。默认值：`auto`。
`response_format`	字符串	否	响应图片格式。`url` 请求图片 URL，`b64_json` 返回 Base64 数据。不传时保留模型或上游渠道的默认行为。
`stream`	布尔值	否	以流式模式生成图片。默认值：`false`。
`partial_images`	整数	否	流式响应中发送的部分图片数量（0–3）。仅在 `stream` 为 `true` 时有效。
`user`	字符串	否	代表最终用户的唯一标识符，可帮助 OpenAI 监控和检测滥用行为。

自定义尺寸

对于 gpt-image-2、gpt-image-2.5-sunburst 和 gpt-image-2.5-flare（包括它们的日期快照），size 可以使用自定义的 宽度x高度 值，例如 1536x864。自定义尺寸必须满足以下所有限制：

宽度和高度必须是 16 的倍数。
宽高比必须在 1:3 到 3:1 之间。
任一边均不得超过 3840 像素。
总像素数必须在 655,360 到 8,294,400 之间。

高于 2560x1440 的分辨率属于实验性功能。

📥 响应

成功响应

两个端点都返回包含图片对象列表的响应。

字段	类型	说明
`created`	整数	图片创建的 Unix 时间戳（秒）
`data`	数组	生成的图片对象列表
`background`	字符串	实际使用的背景设置（`transparent` 或 `opaque`）
`output_format`	字符串	实际使用的输出格式（`png`、`webp` 或 `jpeg`）
`quality`	字符串	实际使用的质量级别（根据模型不同，可以是 `low`、`medium`、`high`、`xhigh` 或 `max`）
`size`	字符串	生成图片的实际尺寸
`usage`	对象	API 调用的令牌使用情况

`usage` 字段

字段	类型	说明
`total_tokens`	整数	使用的总令牌数
`input_tokens`	整数	输入使用的令牌数
`output_tokens`	整数	输出使用的令牌数
`input_tokens_details`	对象	输入令牌的详细分类：`text_tokens` 和 `image_tokens`

图片对象

data 数组中的每个对象包含：

字段	类型	说明
`url`	字符串	图片地址。当请求 `response_format=url` 时返回；可能是上游原生 URL，也可能是 Base64 转存后生成的临时签名 URL。
`b64_json`	字符串	Base64 编码的图片数据。当请求 `response_format=b64_json`、使用上游默认 Base64 行为，或 URL 交付发生允许回退的故障时返回。
`revised_prompt`	字符串	如果提示有任何修改，则包含用于生成图片的修改后的提示

每个图片对象会包含 url 或 b64_json，调用方不应假定两个字段同时存在。URL 响应示例：

{
  "url": "https://cdn.example.com/generated-images/...?...",
  "revised_prompt": "一只可爱的小海獭在水中嬉戏,它有着圆圆的眼睛和毛茸茸的皮毛"
}

响应格式与 URL 交付

`response_format`	行为
不传	保留模型或上游渠道的默认响应格式。GPT Image 模型通常返回 `b64_json`。
`b64_json`	请求在响应中返回 Base64 图像数据。
`url`	请求在响应中返回 URL。原生 URL 会直接返回；符合条件的 Base64 结果会存储后转换为临时签名 URL。

临时 URL 会过期，客户端应在收到响应后及时下载或转存图片，不应将其作为永久地址保存。当 URL 交付过程中发生可回退故障时，API 可能返回 Base64，并设置响应头 X-Image-Delivery-Fallback: base64。客户端使用 response_format=url 时应同时检查响应字段和该响应头。

返回的 URL 已包含访问签名，可直接通过 HTTP GET 下载，不需要附加 API Authorization 请求头。查询参数是签名的一部分，下载时必须保留完整 URL：

IMAGE_URL=$(jq -r '.data[0].url // empty' response.json)
test -n "$IMAGE_URL" && curl --fail --location "$IMAGE_URL" --output generated.png

URL 交付适用于返回完整 JSON 的非流式请求。不要将 response_format=url 与 stream=true 组合使用；流式图片请求应按对应模型的流式响应格式处理。

URL 交付错误

HTTP 状态码	错误码	处理建议
`400`	参数错误	确认 `response_format` 仅使用小写的 `url` 或 `b64_json`。
`502`	`image_url_delivery_failed`	图像已生成，但严格模式下存储或签名失败。可稍后重试，避免立即高频重试。
`502`	`image_response_too_large`	生成响应超过服务端允许的处理上限。减少单次生成数量或图片尺寸。
`503`	`image_url_delivery_unavailable`	当前模型、API 密钥或运行环境尚未提供 URL 交付。可改用 `b64_json`，或等待管理员启用。
`503`	其他 `image_delivery_*` 错误	URL 交付容量或运行状态暂时不可用。按退避策略重试。

🌟 最佳实践

Prompt 编写建议

使用清晰具体的描述
指定重要的视觉细节
描述期望的艺术风格和氛围
注意构图和视角的说明

参数选择建议

尺寸选择
- 1024x1024：通用场景的最佳选择
- 1536x1024/1024x1536：适合横版/竖版场景
质量选择
- quality=high：用于需要精细细节的图像
- quality=xhigh 或 quality=max：仅适用于 GPT Image 2.5；当可以接受更高延迟和成本时，用于需要更多细节的最终成品
- quality=auto：让模型自动选择最优质量

常见问题

图片生成失败
- 检查 prompt 是否符合内容政策
- 确认文件格式和大小限制
- 验证 API 密钥权限
结果与预期不符
- 优化 prompt 描述
- 调整质量和风格参数
- 考虑使用图片编辑或变体功能

OpenAI 图像格式（Image）

目录