图像模型进阶用户更新于
POST/v1/images/generations
GPT Image 2.5 Sunburst
请求 ID gpt-image-2.5-sunburst
协议
POST /v1/images/generations· 生成图片示例POST /v1/images/edits· 编辑图片示例GET /v1/images/tasks/{task_id}· 查询图片任务示例
认证
请求需要 API Key。在控制台的 API Key 管理 获取密钥。发送 JSON 请求时，设置 Content-Type: application/json。
Authorization: Bearer YOUR_API_KEY
请求参数
POST /v1/images/generations
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
model | string | 必填 | 填写此模型的请求 ID gpt-image-2.5-sunburst. |
prompt | string | 必填 | 描述要生成的图像。 |
aspect_ratio | string | 选填 | 输出图像的宽高比。 可用值 1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 21:9. 默认 1:1. |
image_size | string | 选填 | 输出分辨率档位。 可用值 1K, 2K, 4K. 默认 1K. |
quality | string | 选填 | 保留旧请求的兼容字段。按分辨率选择规格，无需传此字段。 |
n | integer | 选填 | 每次请求生成一张。 默认 1. |
image_urls | string[] | 选填 | JSON 参考图数组。每项可为公开 HTTPS 图片链接或 Base64 图片 data URL。 兼容字段 image_input. 参考图上限 4. |
?async | string | 选填 | URL 查询参数。传 1、true 或 yes 返回 202 和 task_id。省略时等待生成结果。 |
POST /v1/images/edits
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
model | string | 必填 | 填写此模型的请求 ID gpt-image-2.5-sunburst. |
prompt | string | 必填 | 描述要对参考图进行的修改。 |
aspect_ratio | string | 选填 | 输出图像的宽高比。 可用值 1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 21:9. 默认 1:1. 编辑时通过 JSON 请求体传入。 |
image_size | string | 选填 | 输出分辨率档位。 可用值 1K, 2K, 4K. 编辑时通过 JSON 请求体传入。 默认 1K. |
quality | string | 选填 | 保留旧请求的兼容字段。按分辨率选择规格，无需传此字段。 |
n | integer | 选填 | 每次请求生成一张。 默认 1. |
image_urls | string[] | 视条件 | JSON 参考图数组。每项可为公开 HTTPS 图片链接或 Base64 图片 data URL。 兼容字段 image_input. 参考图上限 4. 使用 JSON 编辑时至少传一张。 |
image[] | file[] | 视条件 | 使用 multipart/form-data 编辑时，至少上传一张图片，可重复传此字段。单文件也可用 image。 参考图上限 4. |
?async | string | 选填 | URL 查询参数。传 1、true 或 yes 返回 202 和 task_id。省略时等待生成结果。 |
请求示例
先将 API Key 设置为本机环境变量 ICODEEASY_API_KEY，并选择支持直接 HTTP 调用的接入点。接入点要求特定客户端时，按对应客户端指南配置。
示例中的素材 URL 和素材 ID 需要替换成自己的有效素材。
Images Generations
bash
curl -sS 'https://api.icodeeasy.cc/v1/images/generations' \
-H "Authorization: Bearer $ICODEEASY_API_KEY" \
-H 'Content-Type: application/json' \
--data '{
"model": "gpt-image-2.5-sunburst",
"prompt": "A watercolor illustration of a paper lantern by a lake.",
"aspect_ratio": "16:9",
"image_size": "1K"
}'
Images Edits
bash
curl -sS 'https://api.icodeeasy.cc/v1/images/edits' \
-H "Authorization: Bearer $ICODEEASY_API_KEY" \
-H 'Content-Type: application/json' \
--data '{
"model": "gpt-image-2.5-sunburst",
"prompt": "Change the background to a pale blue wall. Preserve the subject.",
"image_urls": [
"https://example.com/reference.png"
],
"aspect_ratio": "16:9",
"image_size": "1K"
}'
查询图片任务
bash
curl -sS 'https://api.icodeeasy.cc/v1/images/tasks/YOUR_TASK_ID' \
-H "Authorization: Bearer $ICODEEASY_API_KEY"
响应与任务
HTTP 200 · 同步成功
使用 ?sync=1 时，成功响应中的 data[].url 是图片地址。created 为 Unix 秒时间戳，id 为任务 ID。
json
{
"id": "d142c93a-de26-40c9-be62-0de840d10960",
"created": 1781599773,
"data": [
{
"url": "https://example.com/generated-image.png"
}
]
}
HTTP 202 · 异步提交
json
{
"task_id": "d142c93a-de26-40c9-be62-0de840d10960",
"status": "pending"
}
使用 ?async=1 后，用同一 API Key 查询 GET /v1/images/tasks/{task_id}。status 可为 pending、completed 或 failed。完成后从 result_url 读取图片地址。
HTTP 200 · 查询到已完成任务
json
{
"task_id": "d142c93a-de26-40c9-be62-0de840d10960",
"status": "completed",
"model": "gpt-image-2.5-sunburst",
"result_url": "https://example.com/generated-image.png"
}
常见错误
查询返回 failed 时读取 error。若存在 error_detail，根据 retryable 判断是否适合重新提交。
完整接入指南 · 查看完整接口指南，了解请求字段、任务状态和响应格式。
能力与限制
text_to_image· 支持image_to_image· 支持image_editing· 支持reference_images· 有条件支持 — 需要以支持的请求格式提供有效参考图- 限制 参考图：最多 4 张 · 分辨率: 1k, 2k, 4k