图片生成与编辑

同步和异步如何选择

同步和异步由请求路径决定，不会自动切换，也不需要额外的异步请求头或请求体字段。

功能	同步请求	异步请求
文生图	POST /v1/images/generations	POST /v1/images/generations/async
图生图	POST /v1/images/edits	POST /v1/images/edits/async
返回方式	保持连接，完成后直接返回图片结果	返回 HTTP 202 和任务 ID，再轮询结果

上述路径均支持去掉 /v1 的根路径别名。查询任务使用 GET /v1/images/tasks/:task_id，详见任务查询。

旧版接入方式已移除

X-KToken-Async: true 和请求体中的 async: true 不再触发本项目的异步任务。旧的 /v1/gpt/images/:task_id 和 /gpt/images/:task_id 查询路由已移除。请迁移到明确的 /async 提交路径及 /images/tasks/:task_id 查询路径。

认证与适用范围

• 使用 Authorization: Bearer <API_KEY>，也支持 x-api-key: <API_KEY>。
• 当前图片路由支持 OpenAI 和 Grok 平台；本文使用 OpenAI 协议的 gpt-image-2 举例，具体模型和参数须由配置的上游支持。
• 分组必须允许图片生成，仍受用户及账户并发限制。
• 同步和异步执行均沿用图片计费逻辑。图片额度计费分组按实际图片数量扣减额度，提交为异步不会绕过计费。

常用参数

同步、异步使用相同的图片业务参数。文生图发送 JSON；图生图既支持 multipart/form-data 上传文件，也支持 application/json 传图片 URL 或 Base64 Data URL。

参数	类型	说明
model	string	图片模型，例如 gpt-image-2
prompt	string	生成提示词或编辑要求
image	file	multipart 图生图上传的原图；不是 JSON 的图片字段
images	array	JSON 图生图的输入图片数组，至少包含一张图片
images[].image_url	string	图片 URL，或 data:image/png;base64,... 格式的完整图片数据
mask	file / object	可选蒙版；multipart 上传文件，JSON 使用 {"image_url":"..."}，支持情况取决于模型
n	integer	图片数量，示例使用 1
size	string	图片尺寸，示例使用 1024x1024
stream	boolean	异步接口不支持 true，会返回 HTTP 400

上游标准字段可参考 OpenAI Images API。本项目的 /async 和任务查询接口属于网关扩展，不是标准 Images SDK 的自动行为。

请求示例

以下为 Bash / curl 示例。BASE_URL 是服务根地址，不包含 /v1；示例入口为 https://example.com。若反向代理有额外挂载前缀，将其加入 BASE_URL，不要重复添加 /v1。

BASE_URL="https://example.com"
API_KEY="替换为你的 API Key"

同步文生图

请求会等待图片生成完成，客户端和反向代理需要允许足够长的等待时间。

curl "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A red ceramic mug on a gray tabletop",
    "n": 1,
    "size": "1024x1024"
  }'

同步成功后直接返回图片 JSON，不返回供轮询的任务 ID。图片字段取决于上游及请求参数，可能为 URL 或 b64_json。以下为 URL 形式的示意响应：

{
  "created": 1788777000,
  "data": [{ "url": "https://example.com/generated-image.png" }]
}

异步文生图

只需在同步路径后加 /async，请求体保持一致：

curl "$BASE_URL/v1/images/generations/async" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A red ceramic mug on a gray tabletop",
    "n": 1,
    "size": "1024x1024"
  }'

接收成功返回 HTTP 202，并带有 Location 和 Retry-After: 3 响应头。示意响应：

{
  "id": "imgtask_example",
  "task_id": "imgtask_example",
  "object": "image.generation.task",
  "status": "pending",
  "created_at": 1788777000,
  "expires_at": 1788863400,
  "poll_url": "/v1/images/tasks/imgtask_example"
}

HTTP 202 仅表示任务已接收，不代表生成成功。取得任务 ID 后，使用提交时的同一个 API Key 每隔 3–5 秒查询一次：

curl "$BASE_URL/v1/images/tasks/imgtask_example" \
  -H "Authorization: Bearer $API_KEY"

pending、queued、processing 时继续等待；completed 时读取 image_url 或 result.data；failed、expired 时读取 error。完整字段与错误处理见任务查询。

同步图生图：文件上传

将 ./input.png 替换为原图路径。使用 -F 时不要手动设置 Content-Type，curl 会自动生成 multipart boundary。

curl "$BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=Change only the mug color to purple" \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "image=@./input.png"

异步图生图：文件上传

同样只改变路径，返回任务后按文生图相同方式轮询：

curl "$BASE_URL/v1/images/edits/async" \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=Change only the mug color to purple" \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "image=@./input.png"

同步图生图：JSON 图片 URL

JSON 图生图使用 images 数组，每张图片放在 image_url 字段中。将示例 URL 替换为服务能够直接读取的图片地址：

curl "$BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Change only the mug color to purple",
    "n": 1,
    "size": "1024x1024",
    "images": [
      { "image_url": "https://example.com/input.png" }
    ]
  }'

同步请求等待生成完成后直接返回图片结果。使用 URL 输入的异步图生图，只需将路径改为 /v1/images/edits/async，JSON 请求体不变。

异步图生图：JSON Base64

将 BASE64_IMAGE_DATA 替换为完整图片文件的 Base64 编码，不要保留占位文字或插入换行。data:image/png;base64, 前缀需与实际图片格式一致；JPEG 使用 data:image/jpeg;base64,。

curl "$BASE_URL/v1/images/edits/async" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Change only the mug color to purple",
    "n": 1,
    "size": "1024x1024",
    "images": [
      { "image_url": "data:image/png;base64,BASE64_IMAGE_DATA" }
    ]
  }'

成功接收返回 HTTP 202 和 task_id，使用相同 API Key 查询 GET /v1/images/tasks/:task_id。使用 Base64 输入的同步图生图，将路径改为 /v1/images/edits 即可，请求体不变。

JSON URL 和 Base64 两种输入方式都支持同步、异步；不要把 JSON 的 images[].image_url 写成 multipart 的 image 文件字段，也不支持通过 images[].file_id 引用文件。

JSON 多图输入

需要多张参考图时，在 images 中添加多个对象。以下请求体可用于同步或异步图生图：

{
  "model": "gpt-image-2",
  "prompt": "Combine the mug and tabletop from the two reference images into one product photograph",
  "n": 1,
  "size": "1024x1024",
  "images": [
    { "image_url": "https://example.com/mug.png" },
    { "image_url": "https://example.com/tabletop.png" }
  ]
}

每个 image_url 也可以换成对应图片的 Base64 Data URL。images 的条目数是输入图片数量，n 是生成结果数量，两者含义不同；具体模型支持的输入数量及编辑能力以服务提供方说明为准。

调用限制与常见错误

• 异步接口不可用时，提交可能返回 HTTP 404，消息为 async image tasks are not enabled。请联系服务提供方确认，不会自动退回同步。
• 异步请求包含 stream=true 时返回 HTTP 400，消息为 streaming image requests cannot be submitted as asynchronous tasks。
• 不支持的平台返回 HTTP 404；分组无图片权限返回 HTTP 403。
• JSON 图生图缺少有效的 images[].image_url 时返回 HTTP 400；images 必须是数组，即使只传一张图片。
• 收到任务 ID 后应查询原任务，不要因尚未完成而重复提交，以免生成和计费多次。