GPT Image 2

不推荐：图片 Edit 接口

图片 Edit 接口不推荐调用，请使用异步生成接口。

不推荐新接入调用 POST /v1/images/edits。需要参考图改图、换装、合成或多图创作时，请调用异步生成接口，并把图片 URL 放入 JSON image 数组。

/v1/images/edits 仅保留给必须使用 OpenAI multipart Edit 语义的旧客户端：

POST /v1/images/edits

异步文生图

创建任务：

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"
  }'

响应会返回任务 ID 和初始状态：

{
  "id": "imgtask_xxx",
  "status": "queued"
}

轮询结果：

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

任务完成后状态为 succeeded，结果在 data 数组中；失败时状态为 failed，错误原因在 error.message。

轮询实现细节

图片任务的推荐接入方式是轮询。创建任务后，应用侧应把任务 ID 持久化，而不是只放在浏览器内存里。建议保存这些字段：

字段	用途
`id`	后续查询任务状态
`status`	页面展示处理中、成功或失败
`created_at`	计算等待时间、排序和排查问题
`model`	展示任务来源，便于用户识别
`prompt` 摘要	任务列表中展示用户输入
`data`	成功后的图片结果
`error.message`	失败时展示可读原因

推荐轮询节奏：

创建任务后立即查询一次，确认任务已记录。
前 30 秒每 2-3 秒查询一次。
之后可放慢到每 5-10 秒一次。
查询到 succeeded 或 failed 后停止轮询。
页面关闭、刷新或用户稍后回来时，用已保存的任务 ID 继续查询。

不要在轮询超时后自动重新创建同一个任务。更稳的做法是保留任务 ID，把页面显示为“仍在处理中”，并允许用户手动刷新状态。 JavaScript 轮询示例：

async function waitForImageJob(jobId, apiKey) {
  const terminal = new Set(["succeeded", "failed"]);
  const startedAt = Date.now();

  while (Date.now() - startedAt < 5 * 60 * 1000) {
    const response = await fetch(`https://kaienapi.com/v1/images/generations/jobs/${jobId}`, {
      headers: {
        Authorization: `Bearer ${apiKey}`,
      },
    });

    const job = await response.json();
    if (terminal.has(job.status)) {
      return job;
    }

    await new Promise((resolve) => setTimeout(resolve, 3000));
  }

  return { id: jobId, status: "running" };
}

结果读取逻辑要同时兼容 URL 和 base64：

const image = job.data?.[0];
const src = image?.url || (image?.b64_json ? `data:image/png;base64,${image.b64_json}` : "");

异步参考图创作

远程图片应使用公网可访问的 OSS/CDN URL，并放入异步任务 JSON 的 image 数组。需要多张网络 URL 做参考图创作、换装、合成或改图时，推荐直接使用 /v1/images/generations/jobs。

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": "保留图 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"
  }'

参考图数量限制

gpt-image-2-2K：最多 8 张参考图，传入 9 张或更多会返回“参考图过多”错误。
gpt-image-2-4K：最多 8 张参考图，传入 9 张或更多会返回“参考图过多”错误。
标准版 gpt-image-2 的上限可能不同，不要在客户端把三个模型统一写死为 8 张；应根据所选模型处理接口返回。

参考图数量按 image 数组中的 URL 数量计算。建议在提交前显示已选数量，但最终限制仍以渠道返回为准。

同步兼容调用

如果客户端必须兼容 OpenAI Images 的同步返回格式，可以继续使用：

POST /v1/images/generations

同步调用会一直等待结果返回。页面、移动端、Serverless、队列 worker 或批量并发场景不建议使用同步等待；这类场景请使用异步任务接口并保存任务 ID。

图片 URL 建议

图片地址必须公网可访问，且在请求期间不会过期。
大图建议先通过 OSS/CDN 图片处理 resize 到合适分辨率，例如长边 1024，再提交给模型。
多张参考图按语义顺序放入 image 数组，并在 prompt 中说明每张图的用途。

常用参数

参数	说明
`model`	`gpt-image-2`、`gpt-image-2-2K` 或 `gpt-image-2-4K`；三个档位均支持同步和异步生成
`prompt`	描述生成目标、参考图用途、保留内容和改动范围
`image`	公网可访问的图片 URL 数组；2K、4K 模型最多 8 张
`size`	优先使用下方推荐尺寸，或传符合限制的自定义尺寸
`quality`	`auto`、`low`、`medium`、`high`
`format`	`png`、`jpeg`、`webp`

这里使用 format，不要写成 output_format。gpt-image-2 当前不支持 n 批量生成；一次请求只生成一张图片，需要多张结果时请发起多次请求。

尺寸	说明
`auto`	默认尺寸
`1024x1024`	方图
`1536x1024`	横图
`1024x1536`	竖图
`2048x2048`	2K 方图
`2048x1152`	2K 横图
`2880x2880`	最大方图
`3840x2160`	最大 16:9 横图
`2160x3840`	4K 竖图

尺寸限制

gpt-image-2-2K 与 gpt-image-2-4K 当前使用相同的尺寸边界。自定义尺寸时需要同时满足：

size 使用 WIDTHxHEIGHT 格式，宽高均为正数。
最大边长不超过 3840px。
宽高都是 16px 的倍数。
长边与短边比例不超过 3:1。
总像素数不少于 655,360，且不超过 8,294,400。

常见边界：

画幅	最大合法尺寸
横图	`3840x2160`
竖图	`2160x3840`
方图	`2880x2880`

3840x2176 会因为总像素超限失败，3856x2048 会因为最长边超限失败，1936x640 会因为比例超过 3:1 失败，1024x1025 会因为不是 16 的倍数失败。

模型名决定模型档位和计费，size 决定实际输出尺寸。 合法的大尺寸不会因为使用 gpt-image-2-2K 而自动缩回 2K；例如传入 3840x2160 时，实际输出可以是 3840x2160。

排查顺序

先跑纯文生图，确认模型可用。
再传一张 OSS/CDN 图片 URL。
单图正常后测试多图数组。
没有图片结果时，记录完整响应并确认图片字段位置。
浏览器、移动端或后端调用超时时，应改为异步任务模式，不要让页面或请求线程长时间等待单个同步请求。

开始使用

图片和视频

AI 工具接入

API Reference

推荐优先使用异步生成接口

不推荐：图片 Edit 接口

异步文生图

轮询实现细节

异步参考图创作

参考图数量限制

同步兼容调用

图片 URL 建议

常用参数

推荐尺寸

尺寸限制

排查顺序

​推荐优先使用异步生成接口

​不推荐：图片 Edit 接口

​异步文生图

​轮询实现细节

​异步参考图创作

​参考图数量限制

​同步兼容调用

​图片 URL 建议

​常用参数

​推荐尺寸

​尺寸限制

​排查顺序

推荐优先使用异步生成接口

不推荐：图片 Edit 接口

异步文生图

轮询实现细节

异步参考图创作

参考图数量限制

同步兼容调用

图片 URL 建议

常用参数

推荐尺寸

尺寸限制

排查顺序