图片生成 API（/v1/images/generations）

兼容 OpenAI Images 协议的图片生成接口，目前提供 gpt-image-2（支持文生图与图生图）。按张数 × 质量档计费，与 token 无关。

端点与认证

POST https://jp.icodeeasy.cc/v1/images/generations

图片生成示例使用正式备用接入域名 https://jp.icodeeasy.cc，路径保持不变。

请求头：

  • Authorization：Bearer <你的 API Key>（必填，sk_ 开头）
  • Content-Type：application/json（必填）

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

请求参数

  • model（string，必填）：当前仅支持 gpt-image-2。
  • prompt（string，必填）：图像描述，中英文均可。上游会做敏感词审核，违规直接拒绝、不扣费。
  • n（integer，默认 1）：生成张数，按张累计计费。
  • size（string，默认 1:1）：输出比例，见下方。也接受 auto（按 1:1 处理）或像素串（如 1024x1024，会换算为最近比例）。
  • resolution（string，默认 1k）：分辨率档位，可选 1k / 2k。
  • quality（string，仅用于计费）：可选 low / medium / high / auto。不会影响上游实际输出，只决定结算价位。未传时按 resolution 推断：1k → low、2k → medium。
  • image_urls（array，可选）：图生图参考图，最多 16 张。元素可为 https://... URL 或 data:image/...;base64,...，可混填。
  • official_fallback（boolean，默认 false）：是否启用官方渠道兜底，透传给上游。

支持的比例与分辨率

支持的比例（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。

分辨率与比例的兼容性：1k / 2k 支持所有 13 个比例。

请求示例

最简文生图

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

指定比例与 2K

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

图生图（多参考图，URL + base64 混填）

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

响应结构

成功响应（HTTP 200，OpenAI Images 兼容）：

{
  "id": "task_01KRBPMVG0ZACTH39J23DEZ3A2",
  "created": 1776748726,
  "data": [
    {
      "url": "https://api.icodeeasy.cc/v1/images/files/20260511/task_01KRBPMVG0ZACTH39J23DEZ3A2-1.png"
    }
  ]
}
  • id：上游任务 ID，便于客服排查
  • created：UTC 秒级时间戳
  • data[].url：中转图片链接，可直接 <img src> 展示

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

图片链接行为

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

  • 直接打开：GET 返回 302，自动跳转到 OSS 临时签名链接，浏览器无感
  • 强制下载：URL 加 ?download=1 触发附件下载（用于"另存为"按钮）
  • 长期有效：中转链接长期可用，每次访问由中转层重签 OSS 链接
  • 访问控制：该路径不需要 API Key，链接本身即凭据。请不要把生成结果链接发到公开场合，任何人持有完整 URL 都能下载

同步语义与超时

接口为同步阻塞：客户端发起请求 → 中转层向上游提交异步任务 → 内部以 3 秒间隔轮询，最长等待 3 分钟（180 秒）。

  • 客户端 HTTP 超时建议 ≥ 200 秒
  • 单张图典型 30~60 秒，多张可能更长
  • 超过 3 分钟未完成会返回 504，错误体含 task_id 便于联系运营查询

错误响应

错误体统一为：

{
  "error": {
    "type": "upstream_error",
    "message": "...",
    "provider": "icodeeasy.cc",
    "task_id": "task_xxx"
  }
}

常见状态：

  • 400 invalid_request_error：参数错误（比例不支持、image_urls 超 16 张等）
  • 401 authentication_error：API Key 缺失或无效
  • 402 payment_required：余额不足 / 月卡额度用尽
  • 429 rate_limit_error：调用频率超限
  • 5xx upstream_error：上游错误，502 = 响应格式异常或转存失败，504 = 任务超时

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

计费

按 张数 × 质量档 固定 ¥ 计费，与 token 无关：

  • low：¥0.10 / 张
  • medium / auto：¥0.30 / 张
  • high：¥0.80 / 张

quality 决定档位；未传则由 resolution 推断。在「用量明细」中此请求记录为 model = gpt-image-2，cost_breakdown 含 image_count / image_cost_rmb / image_urls，可在历史里直接复制链接、下载。

与 OpenAI Images API 的差异

  • 模型：仅 gpt-image-2，没有 gpt-image-1 / dall-e-3
  • size：推荐用纵横比（16:9 等）；像素串会被换算为最近的比例
  • resolution：OpenAI 不存在的新字段（1k / 2k），用于显式选档
  • quality：取值 low / medium / high / auto，仅用于计费，与 OpenAI 的 standard / hd 语义不同
  • response_format：不支持 b64_json，固定返回 URL
  • image_urls：原生支持图生图，最多 16 张，URL 与 base64 可混填
  • 任务 ID：响应里透传 id（上游 task_id），便于排错
注册并获取 API Key