图片生成 API

图片 API 兼容 OpenAI Images 协议。下面是精选、已核验的八个模型：全部可通过 generations 文生图；只有明确标注支持 /edits 的模型才能调用编辑端点。

提供两个端点：

• /v1/images/generations — 生成图片；部分模型也可在此端点提交参考图
• /v1/images/edits — 仅供下表明确标注的模型编辑图片，兼容 OpenAI 原生 edits 调用习惯

端点与认证

POST https://api.icodeeasy.cc/v1/images/generations
POST https://api.icodeeasy.cc/v1/images/edits

主 Base URL 使用 https://api.icodeeasy.cc。https://jp.icodeeasy.cc 与 https://sg.icodeeasy.cc 是备用 / fallback 域名，切换时路径保持不变。

请求头：

• Authorization：Bearer <你的 API Key>（必填，sk_ 开头）
• Content-Type：application/json（JSON 形式）或 multipart/form-data（文件上传形式）

也接受不带 /v1 前缀的 POST /images/generations、POST /images/edits，效果相同。

两种入站形式

接口同时支持两种请求体：

1. JSON（Content-Type: application/json）：参考图以 URL 或 base64 放进 image_urls 字段。最常用。
2. multipart/form-data：参考图以 image[] 文件上传，其它参数走 form 字段。与 OpenAI 原生 edits 一致，适合直接上传本地图片。

请求参数

• model（必填）：使用上表八个精选模型 ID 之一。
• prompt（必填）：图像描述，中英文均可。上游会做内容安全审核，违规直接拒绝、不扣费。
• n（默认 1）：生成张数，按张累计计费。
• size（默认 1:1）：输出比例，见下方。也接受 auto（按 1:1 处理）或像素串（如 1536x1024）。
• resolution（默认 1k）：Gemini 2.5 仅接受 1k；表中的 Gemini 3.x 接受 1k / 2k / 4k。不要用此字段为 gpt-image-2 选择档位。
• quality（仅 gpt-image-2 计费使用）：可选 low / medium / high / auto。不影响实际输出，只决定 gpt-image-2 结算价位。Gemini 模型忽略该字段，按模型固定价计费。
• image_urls / image_input（可选，JSON 形式）：图生图参考图，最多 4 张。元素可为 https://... URL（须公网可访问的 https）或 data:image/...;base64,...，可混填。两个字段是别名，效果相同。
• image[]（可选，multipart 形式）：图生图参考图文件，可多个，等价于 image_urls 的文件上传写法。

参考图链路提示：URL 必须是 https://（http 会被拒绝）；base64 必须是合法的 data:image/*;base64, 格式。

支持的比例与分辨率

支持的比例（size）：1:1 / 3:2 / 2:3 / 4:3 / 3:4 / 5:4 / 4:5 / 16:9 / 9:16 / 2:1 / 1:2 / 21:9 / 9:21 / auto。

gemini-2.5-flash-image 仅支持 1k；表中的 Gemini 3.x 支持 1k / 2k / 4k。gpt-image-2 用 size 控制输出比例或像素尺寸，不公开宣称分辨率档位。

同步 / 异步模式

默认同步：请求阻塞到出图，直接返回 OpenAI 兼容结构 data[].url，一次拿图。

异步：在 URL 加 ?async=1（也接受 true / yes），立即返回 task_id，再自行轮询任务结果。适合不想长时间挂住连接、需要进度反馈、或批量提交的场景。

请求示例

最简文生图（同步）

curl -X POST https://api.icodeeasy.cc/v1/images/generations \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只橘猫坐在窗台上看夕阳，水彩画风格"
  }'

使用 Gemini 3.x 指定比例与 2K

curl -X POST https://api.icodeeasy.cc/v1/images/generations \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "a corgi astronaut on the moon, cinematic",
    "size": "16:9",
    "resolution": "2k"
  }'

Gemini 文生图

curl -X POST https://api.icodeeasy.cc/v1/images/generations \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "一间未来感咖啡馆，清晨阳光，写实摄影风格",
    "size": "16:9",
    "resolution": "1k"
  }'

图生图：用图片 URL（JSON）

curl -X POST https://api.icodeeasy.cc/v1/images/edits \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "把这个人物改成 70 岁",
    "size": "1536x1024",
    "image_urls": ["https://example.com/photo.png"]
  }'

图生图：上传本地图片（multipart）

curl -X POST https://api.icodeeasy.cc/v1/images/edits \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -F "model=gpt-image-2" \
  -F "prompt=把这个人物改成 70 岁" \
  -F "size=1536x1024" \
  -F "image[]=@/path/to/photo.png"

图生图：多参考图融合（URL + base64 混填）

curl -X POST https://api.icodeeasy.cc/v1/images/edits \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "把这两张照片融合成一张海报",
    "size": "4:3",
    "image_urls": [
      "https://example.com/photo-a.jpg",
      "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    ]
  }'

异步提交 + 轮询

# 1) 提交，立即拿 task_id
curl -X POST "https://api.icodeeasy.cc/v1/images/edits?async=1" \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "把这个人物改成 70 岁",
    "image_urls": ["https://example.com/photo.png"]
  }'
# → {"status":"pending","task_id":"d142c93a-..."}

# 2) 轮询直到 completed
curl "https://api.icodeeasy.cc/v1/images/tasks/d142c93a-..." \
  -H "Authorization: Bearer sk_xxxxxxxx"
# → {"status":"completed","result_url":"https://...png","cost":0.2,...}

响应结构

同步成功（HTTP 200，OpenAI Images 兼容）：

{
  "id": "3e0c77bb-9cbd-4c44-9549-bff1b4060623",
  "created": 1781599773,
  "data": [
    {
      "url": "https://api.icodeeasy.cc/v1/images/files/gpt-image-2/20260616/3e0c77bb-...-1.png"
    }
  ]
}

异步提交（HTTP 202）：

{ "status": "pending", "task_id": "d142c93a-de26-40c9-be62-0de840d10960" }

异步任务查询（GET /v1/images/tasks/{task_id}）：

{
  "task_id": "d142c93a-de26-40c9-be62-0de840d10960",
  "status": "completed",
  "model": "gpt-image-2",
  "cost": 0.2,
  "result_url": "https://api.icodeeasy.cc/v1/images/files/gpt-image-2/20260616/d142c93a-...-1.png"
}

• status：pending / completed / failed
• data[].url / result_url：图片链接，可直接 <img src> 展示
• id / task_id：任务 ID，便于客服排查

接口固定返回 URL，不支持 response_format: b64_json。如需图片字节请自行下载。

图片链接行为

data[].url 形如 https://api.icodeeasy.cc/v1/images/files/gpt-image-2/YYYYMMDD/<id>-<seq>.png：

• 直接打开：GET 返回 302，自动跳转到实际图片地址，浏览器无感
• 强制下载：URL 加 ?download=1 触发附件下载
• 长期有效：该链接长期可用
• 访问控制：该路径不需要 API Key，链接本身即凭据。请勿把生成结果链接发到公开场合，任何人持有完整 URL 都能下载

同步语义与超时

默认同步模式下，请求会一直挂到出图：

• 客户端 HTTP 超时建议 ≥ 200 秒
• 单张图典型 30~60 秒，图生图、2K、多张可能更长
• 不想长时间等待时，改用异步模式（?async=1）立即拿 task_id，再轮询

错误响应

错误体统一为：

{
  "error": {
    "type": "server_error",
    "message": "...",
    "provider": "icodeeasy.cc"
  }
}

常见状态：

• 400 invalid_request_error：参数错误（比例不支持、参考图超 4 张、参考图非 https/非合法 base64 等）
• 401 authentication_error：API Key 缺失或无效
• 402 payment_required：余额不足 / 月卡额度用尽
• 429 rate_limit_error：调用频率超限
• 5xx：服务暂时不可用或生成失败，可稍后重试

失败请求不计费，余额不会被扣除。

计费

按 张数 × 模型 / 档位 固定 ¥ 计费，与 token 无关。

gpt-image-2 按 quality 档位计费：

• low：¥0.10 / 张
• medium / auto（默认）：¥0.20 / 张
• high：¥0.40 / 张

Gemini 图片模型按模型固定价计费：

在「用量明细」中请求会记录实际 model，cost_breakdown 含 image_count / image_cost_rmb / image_urls，可在历史里直接复制链接、下载。

与 OpenAI Images API 的差异

• 模型：使用上表八个精选模型 ID 之一；没有 gpt-image-1 / dall-e-3
• 端点：所有精选模型都支持 generations；只有上表明确标注的模型可使用 edits
• size：推荐用纵横比（16:9 等）；像素串也可用
• resolution：Gemini 2.5 仅支持 1k；表中的 Gemini 3.x 支持 1k / 2k / 4k；gpt-image-2 不公开宣称分辨率档位
• quality：取值 low / medium / high / auto，仅用于计费，与 OpenAI 的 standard / hd 语义不同
• response_format：不支持 b64_json，固定返回 URL
• 参考图：仅上表标注支持的模型可用；支持的请求使用 image_urls / image_input（JSON）或 image[]（multipart），具体限制以模型为准
• 异步：OpenAI 无此模式；本接口 ?async=1 返回 task_id，轮询 /v1/images/tasks/{id} 取结果
• 任务 ID：响应里透传 id / task_id，便于排错