GPT Image 2

不推荐：图片 Edit 接口

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

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

/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 或 images 数组中的图片数量计算，包含 URL 和 Base64 图片。建议在提交前显示已选数量，但最终限制以接口返回为准。

Base64 单图输入

本地参考图可以直接编码为 Base64，放入 images 普通字符串数组。服务会流式解码并上传到临时 COS 存储，再把参考图 URL 传给渠道，不需要客户端先单独上传。以下示例的 Base64 是输入参考图；response_format: "url" 表示输出仍返回图片 URL。

API_KEY="<YOUR_API_KEY>"
IMAGE_BASE64="$(base64 < /path/image.jpg | tr -d '\r\n')"

curl -sS 'https://kaienapi.com/v1/images/generations/jobs' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<EOF
{
  "model": "gpt-image-2",
  "prompt": "保留参考图的主体，把背景改成浅蓝色。",
  "images": ["data:image/jpeg;base64,$IMAGE_BASE64"],
  "size": "1024x1024",
  "quality": "low",
  "response_format": "url"
}
EOF

Base64 多图输入

多张参考图按顺序放入同一个 images 数组，在 prompt 中说明各自用途：

API_KEY="<YOUR_API_KEY>"
IMAGE_1="$(base64 < /path/image1.jpg | tr -d '\r\n')"
IMAGE_2="$(base64 < /path/image2.jpg | tr -d '\r\n')"

curl -sS 'https://kaienapi.com/v1/images/generations/jobs' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<EOF
{
  "model": "gpt-image-2",
  "prompt": "保留第一张图的主体，参考第二张图的背景和风格，生成一张融合图片。",
  "images": [
    "data:image/jpeg;base64,$IMAGE_1",
    "data:image/jpeg;base64,$IMAGE_2"
  ],
  "size": "1024x1024",
  "quality": "low",
  "response_format": "url"
}
EOF

替换图片路径即可。PNG 图片使用 data:image/png;base64,，WebP 使用 data:image/webp;base64,，GIF 使用 data:image/gif;base64,；前缀必须与实际图片格式一致。也支持不带前缀的标准 Base64。提交成功返回 HTTP 202 和任务 id。使用返回的 ID 每隔约 5 秒查询一次：

JOB_ID="<返回的任务id>"

curl -sS "https://kaienapi.com/v1/images/generations/jobs/$JOB_ID" \
  -H "Authorization: Bearer $API_KEY"

查询到 succeeded 或 failed 后停止；成功时结果 URL 在 data[0].url。不要因为轮询超时而自动重新提交任务。

输入格式与上传限制

images 支持普通字符串数组，也支持 [{ "image_url": "data:image/jpeg;base64,..." }] 对象数组；可混合 URL 和 Base64，保留输入顺序。
image、image[]、images 是参考图字段的兼容写法，一次请求只使用其中一种。
Base64 图片支持 PNG、JPEG、WebP、GIF。默认每张解码后最多 10 MiB，每次最多上传 14 张 Base64 图片、合计最多 64 MiB，实际限制以服务配置为准。
URL 参考图不占 Base64 上传数量，但总参考图数量仍受模型和渠道限制；14 张上传上限不代表所有模型都支持 14 张参考图。
同一请求中的重复图片分别上传，不会合并；未使用显式幂等键时，不同请求分别创建任务。
多图输入是多张参考图，不是生成多张结果图；Base64 输入与 response_format 输出格式相互独立。

同步兼容调用

如果客户端必须兼容 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` / `images`	参考图 URL 数组；异步 JSON 请求也支持 Base64 和 URL 混传，2K、4K 模型最多 8 张参考图
`size`	优先使用下方推荐尺寸，或传符合限制的自定义尺寸
`quality`	`auto`、`low`、`medium`、`high`
`format`	`png`、`jpeg`、`webp`

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

分辨率档位

使用基础模型 gpt-image-2 时，服务主要根据像素 size 的最长边选择模型和计费档位：

条件	模型	档位
`size` 最长边不超过 `1792px`	`gpt-image-2`	1K
`size` 最长边为 `1793px` 至 `2688px`	`gpt-image-2-2K`	2K
`size` 最长边为 `2689px` 至 `3840px`	`gpt-image-2-4K`	4K

GPT Image 2 只使用 size 选择分辨率档位，其他图片档位兼容字段不参与选档。未传像素 size、使用 auto 或仅传画幅比例时，基础模型默认按 1K。档位用于选择模型和计费。size 仍表示实际输出宽高，并继续受下方尺寸限制约束。

尺寸	说明
`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 决定实际输出尺寸和优先档位。

排查顺序

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

开始使用

图片和视频

语音和音频

AI 工具接入

API Reference

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

不推荐：图片 Edit 接口

异步文生图

轮询实现细节

异步参考图创作

参考图数量限制

Base64 单图输入

Base64 多图输入

输入格式与上传限制

同步兼容调用

图片 URL 建议

常用参数

分辨率档位

推荐尺寸

尺寸限制

排查顺序

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

​不推荐：图片 Edit 接口

​异步文生图

​轮询实现细节

​异步参考图创作

​参考图数量限制

​Base64 单图输入

​Base64 多图输入

​输入格式与上传限制

​同步兼容调用

​图片 URL 建议

​常用参数

​分辨率档位

​推荐尺寸

​尺寸限制

​排查顺序

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

不推荐：图片 Edit 接口

异步文生图

轮询实现细节

异步参考图创作

参考图数量限制

Base64 单图输入

Base64 多图输入

输入格式与上传限制

同步兼容调用

图片 URL 建议

常用参数

分辨率档位

推荐尺寸

尺寸限制

排查顺序