图像模型进阶用户更新于
POST/v1/images/generations
GPT Image 2
请求 ID gpt-image-2
协议
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. |
prompt | string | 必填 | 描述要生成的图像。 |
size | string | 选填 | 建议使用像素尺寸，例如 1536x1024。也接受 auto 或比例写法（如 16:9）。不同接入点对比例写法的处理可能不同。 默认 1024x1024. |
image_size | string | 选填 | 输出分辨率档位。 可用值 1K, 2K, 4K. 省略时根据 size 推导。 默认 1K. |
quality | string | 选填 | 生成质量设置。 可用值 auto, low, medium, high. |
n | integer | 选填 | 单次请求的图片数量，建议保持为 1。 默认 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. |
prompt | string | 必填 | 描述要对参考图进行的修改。 |
size | string | 选填 | 建议使用像素尺寸，例如 1536x1024。也接受 auto 或比例写法（如 16:9）。不同接入点对比例写法的处理可能不同。 默认 1024x1024. |
image_size | string | 选填 | 输出分辨率档位。 可用值 1K, 2K, 4K. 省略时根据 size 推导。 编辑时通过 JSON 请求体传入。 默认 1K. |
quality | string | 选填 | 生成质量设置。 可用值 auto, low, medium, high. |
n | integer | 选填 | 单次请求的图片数量，建议保持为 1。 默认 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",
"prompt": "A watercolor illustration of a paper lantern by a lake.",
"size": "1536x1024",
"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",
"prompt": "Change the background to a pale blue wall. Preserve the subject.",
"image_urls": [
"https://example.com/reference.png"
],
"size": "1536x1024",
"image_size": "1K"
}'
Images Edits · 上传图片并编辑
bash
curl -sS 'https://api.icodeeasy.cc/v1/images/edits' \
-H "Authorization: Bearer $ICODEEASY_API_KEY" \
-F 'model=gpt-image-2' \
-F 'prompt=Change the background to a pale blue wall. Preserve the subject.' \
-F 'size=1536x1024' \
-F 'image[]=@/path/to/photo.png'
查询图片任务
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",
"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