图片生成

重要：优先使用异步生成接口

图片 Edit 接口不推荐调用。GPT Image 2 的 1K、2K、4K 档位均支持同步和异步生成，耗时较长时优先使用异步接口。

新接入统一推荐 POST /v1/images/generations/jobs。POST /v1/images/edits 不推荐调用。参考图改图也请使用异步生成接口的 JSON image 数组。

gpt-image-2、gpt-image-2-2K 和 gpt-image-2-4K 都可以调用 /v1/images/generations；同步请求会在服务内部等待异步任务完成。批量并发或客户端超时较短时，请使用 /v1/images/generations/jobs。

图片生成优先使用异步任务：

POST /v1/images/generations/jobs

创建任务后保存任务 ID，再轮询查询结果。页面、移动端、Serverless、批量并发和参考图改图场景都建议使用这种方式，避免客户端长时间等待单个同步请求。同步兼容调用使用：

POST /v1/images/generations

URL 参考图创作、换装、合成或改图，推荐使用异步任务 JSON 接口，把公网图片 URL 放到 image 数组。 multipart 图片 Edit 接口仅用于兼容旧客户端，不推荐新接入：

POST /v1/images/edits

Gemini 图像模型不走这里的图片接口。它们使用聊天接口返回图片，宽高比放在 extra_body.google.image_config.aspect_ratio；不同模型对 16:9 的支持不完全一致。见 Gemini 图像生成。

文生图

curl https://kaienapi.com/v1/images/generations/jobs \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "生成一张干净的耳机产品海报，白色背景，柔和光线",
    "size": "1024x1024",
    "quality": "low",
    "format": "jpeg",
    "n": 1
  }'

参考图创作

如果使用远程图片 URL，优先把 OSS 或 CDN 图片 URL 放到异步任务 JSON 的 image 数组里。多张网络 URL 做参考图创作、换装、合成或改图时，推荐使用 /v1/images/generations/jobs 创建任务并轮询结果。

{
  "model": "gpt-image-2",
  "prompt": "保留图 1 的人物特征，服饰参考图 2，鞋子参考图 3，生成白底全身 look 图。",
  "image": [
    "https://oss.example.com/model.jpg?x-oss-process=image/resize,w_1024/quality,q_85",
    "https://oss.example.com/outfit.jpg?x-oss-process=image/resize,w_1024/quality,q_85",
    "https://oss.example.com/shoes.jpg?x-oss-process=image/resize,w_1024/quality,q_85"
  ],
  "size": "960x1280",
  "quality": "standard",
  "format": "png",
  "n": 1
}

大图建议先通过 OSS/CDN 图片处理 resize 到合适分辨率，例如长边 1024，并确保 URL 在请求期间不会过期。

结果读取

图片接口可能返回：

图片 URL。
b64_json。
异步任务 ID。

接入时不要只写死一个字段路径。需要长期访问的结果应保存到自己的对象存储。

推荐轮询流程

图片生成、参考图创作和改图任务首推“创建任务 + 轮询结果”。不要让页面、移动端或 Serverless 函数一直等待同步图片请求返回。

调用 POST /v1/images/generations/jobs 创建任务。
保存返回的 id、创建时间、请求参数摘要和当前状态。
每隔 2-3 秒调用 GET /v1/images/generations/jobs/{job_id} 查询一次。
查询到 queued 或 running 时继续等待，并在页面展示处理中状态。
查询到 succeeded 时读取 data 数组，展示图片，并把需要长期访问的图片保存到对象存储。
查询到 failed 时读取 error.message，把任务标记为失败，并允许用户修改 prompt 或参考图后重新提交。

轮询建议设置最长等待时间，例如 3-5 分钟。超过后不要丢弃任务 ID，可以把页面状态显示为“仍在处理中”，稍后继续用同一个任务 ID 查询。用户刷新页面或稍后回来时，也应从你保存的任务 ID 恢复进度。

JOB_ID="imgtask_xxx"

curl "https://kaienapi.com/v1/images/generations/jobs/$JOB_ID" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

返回示例：

{
  "id": "imgtask_xxx",
  "status": "succeeded",
  "data": [
    {
      "url": "https://example.com/result.png"
    }
  ]
}

前端或后端轮询时只在终态停止：succeeded、failed。如果网络请求临时失败，可以等待下一轮继续查询；不要立刻重复创建新任务，避免同一张图被重复生成。

选错接口时的表现

如果把 Gemini 图像模型提交到 /v1/images/generations，请求可能返回“不支持图片生成接口”的错误。这个错误通常不是宽高比参数失效，而是接口选错了。这类模型请改用：

POST /v1/chat/completions

开始使用

图片和视频

AI 工具接入

API Reference

重要：优先使用异步生成接口

文生图

参考图创作

结果读取

推荐轮询流程

选错接口时的表现

​重要：优先使用异步生成接口

​文生图

​参考图创作

​结果读取

​推荐轮询流程

​选错接口时的表现

重要：优先使用异步生成接口

文生图

参考图创作

结果读取

推荐轮询流程

选错接口时的表现