异步生图

异步生图用于生产环境中的长耗时图片生成。客户端先提交任务，服务端返回任务 ID 并在后台执行生图，客户端再通过轮询或 SSE 获取结果。

同一个 /v1/images/tasks 会按 model 分发到不同上游协议。一个任务只接受一个模型、一个提示词和 n 张图片。

调用异步生图必须使用 生图 API Key。该 Key 需要绑定批量生图分组，请先按创建 API Key 中的步骤创建。

当前支持：

模型	批量生图分组模型平台	上游协议
`gpt-image-*`、`image2`	OpenAI	OpenAI Images API
`gemini-2.5-flash-image`	Gemini	Gemini native `generateContent`
`gemini-3.1-flash-image`	Gemini	Gemini native `generateContent`

Gemini 生图请使用官方模型名，不使用 banana、nano-banana 等别名。

提交任务

接口说明：

项目	值
Method	`POST`
Path	`/v1/images/tasks`
Content-Type	`application/json`
成功状态码	`202`
认证	`Authorization: Bearer YOUR_API_KEY`
Key 要求	必须使用绑定批量生图分组的生图 API Key；请求模型必须存在于该批量生图分组中

请求参数：

参数	类型	必填	说明
`model`	string	否	图片模型。默认 `gpt-image-2`。`image2` 会被规范化为 `gpt-image-2`；Gemini 使用官方模型名。
`prompt`	string	是	生图提示词，不能为空。
`size`	string	否	输出尺寸。OpenAI 透传给 Images API；Gemini 会据此推导 `imageConfig.imageSize` 和常见宽高比。
`n`	integer	否	生成图片数量，默认 `1`，必须大于 `0`，并受服务端单任务上限限制。
`stream`	boolean	否	必须为 `false` 或不传；异步任务不支持流式上游响应。
`response_format`	string	否	仅 OpenAI。未传时服务端会设置为 `b64_json`。
`quality`	string	否	OpenAI 原生图片参数，按上游支持情况透传。
`background`	string	否	OpenAI 原生图片参数，按上游支持情况透传。
`output_format`	string	否	OpenAI 原生图片参数，按上游支持情况透传。
`moderation`	string	否	OpenAI 原生图片参数，按上游支持情况透传。

Gemini 可选参数：

参数	类型	说明
`image_size` / `imageSize`	string	生成尺寸档位，支持 `1K`、`2K`、`4K`，也可传常见尺寸字符串由服务端归一化。
`aspect_ratio` / `aspectRatio`	string	支持 `1:1`、`16:9`、`9:16`、`4:3`、`3:4`。
`temperature`、`top_p` / `topP`、`top_k` / `topK`、`seed`、`max_output_tokens` / `maxOutputTokens`	number	写入 Gemini `generationConfig`。
`generation_config` / `generationConfig`	object	透传并合并到 Gemini `generationConfig`。服务端会确保包含图片输出 modality。
`image_config` / `imageConfig`	object	透传并合并到 `generationConfig.imageConfig`。
`system_instruction` / `systemInstruction`	string/object	可选 Gemini 系统指令。
`safety_settings` / `safetySettings`	array	可选 Gemini 安全设置。

不支持的请求格式：

格式	说明
`multipart/form-data`	异步任务当前只支持 JSON 生图请求。
图片编辑	异步任务当前只对应 `/v1/images/generations`。
多 prompt 批量	一个任务只接受一个 `prompt`。
普通 API Key	普通分组 Key 不能提交异步生图任务。

OpenAI 请求示例：

bash

curl https://llmapi.site/v1/images/tasks \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "image2",
    "prompt": "a clean studio product photo of a matte black water bottle",
    "size": "1024x1024",
    "n": 2
  }'

响应示例：

json

{
  "id": "8b17fd33b0e947a08cb417e81e9ea9da",
  "task_id": "8b17fd33b0e947a08cb417e81e9ea9da",
  "object": "image.task",
  "status": "queued",
  "created_at": "2026-05-14T05:13:00Z",
  "model": "gpt-image-2",
  "n": 2,
  "size": "1024x1024",
  "estimated_cost": 0.12,
  "poll_url": "/v1/images/tasks/8b17fd33b0e947a08cb417e81e9ea9da",
  "event_url": "/v1/images/tasks/events"
}

Gemini 请求示例：

bash

curl https://llmapi.site/v1/images/tasks \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-2.5-flash-image",
    "prompt": "a clean studio product photo of a matte black water bottle",
    "image_size": "1K",
    "aspect_ratio": "1:1",
    "n": 1
  }'

查询任务

接口说明：

项目	值
Method	`GET`
Path	`/v1/images/tasks/{task_id}`
认证	`Authorization: Bearer YOUR_API_KEY`
权限	只能查询当前 API Key 创建的任务

Path 参数：

参数	类型	必填	说明
`task_id`	string	是	提交任务返回的任务 ID。

请求示例：

bash

curl https://llmapi.site/v1/images/tasks/8b17fd33b0e947a08cb417e81e9ea9da \
  -H 'Authorization: Bearer YOUR_API_KEY'

状态说明：

状态	说明
`queued`	任务已入队，等待 worker 执行。
`running`	任务正在执行。
`succeeded`	任务成功完成，`result` 中包含图片结果。
`failed`	任务失败，`error` 中包含失败原因；不扣费并释放预扣。
`timeout`	任务超时；不扣费、释放预扣，服务端不会自动重试。
`canceled`	任务已取消；不扣费并释放预扣。

成功任务响应示例：

json

{
  "id": "8b17fd33b0e947a08cb417e81e9ea9da",
  "task_id": "8b17fd33b0e947a08cb417e81e9ea9da",
  "object": "image.task",
  "status": "succeeded",
  "created_at": "2026-05-14T05:13:00Z",
  "started_at": "2026-05-14T05:13:02Z",
  "finished_at": "2026-05-14T05:13:42Z",
  "model": "gpt-image-2",
  "n": 2,
  "size": "1024x1024",
  "estimated_cost": 0.12,
  "actual_cost": 0.12,
  "result": {
    "data": [
      {
        "index": 0,
        "url": "https://oss.example.com/images/task-0.png?signature=...",
        "content_type": "image/png",
        "size_bytes": 1048576,
        "expires_at": "2026-05-21T05:13:42Z"
      }
    ]
  },
  "poll_url": "/v1/images/tasks/8b17fd33b0e947a08cb417e81e9ea9da",
  "event_url": "/v1/images/tasks/events"
}

Gemini 任务的响应结构相同，model 会保留请求中的官方 Gemini 模型名：

json

{
  "id": "8b17fd33b0e947a08cb417e81e9ea9da",
  "task_id": "8b17fd33b0e947a08cb417e81e9ea9da",
  "object": "image.task",
  "status": "queued",
  "created_at": "2026-05-14T05:13:00Z",
  "model": "gemini-2.5-flash-image",
  "n": 1,
  "size": "1K",
  "poll_url": "/v1/images/tasks/8b17fd33b0e947a08cb417e81e9ea9da",
  "event_url": "/v1/images/tasks/events"
}

失败任务响应示例：

json

{
  "id": "8b17fd33b0e947a08cb417e81e9ea9da",
  "task_id": "8b17fd33b0e947a08cb417e81e9ea9da",
  "object": "image.task",
  "status": "failed",
  "model": "gpt-image-2",
  "n": 1,
  "error": {
    "code": "upstream_error",
    "message": "image generation failed"
  }
}

取消任务

接口说明：

项目	值
Method	`POST`
Path	`/v1/images/tasks/{task_id}/cancel`
认证	`Authorization: Bearer YOUR_API_KEY`
权限	只能取消当前 API Key 创建的任务
可取消状态	`queued`

请求示例：

bash

curl -X POST https://llmapi.site/v1/images/tasks/8b17fd33b0e947a08cb417e81e9ea9da/cancel \
  -H 'Authorization: Bearer YOUR_API_KEY'

说明：

只有仍在排队的任务可以取消。
已进入 running 的任务可能已经提交到上游，该接口不会中断上游执行。
任务已经进入终态时会返回冲突错误。

计费行为

阶段	行为
提交前	校验余额、API Key 状态、分组权限和内容风控。
入队时	按模型、尺寸、数量预估成本并进行余额预扣。
成功时	按实际生成结果结算；实际费用低于预扣会退回差额，高于预扣会补扣差额，余额可能变为负数。
用量记录	任务成功结算后写入用量记录；用量记录写入异常不改变任务的成功状态。
失败、超时、取消	不扣费，并释放全部预扣额度。

失败和超时任务不会自动重试。调用方如需重试，应重新提交一个新任务。

异步任务当前不支持普通订阅计费分组。请使用绑定批量生图分组的生图 API Key；普通订阅分组调用会返回 IMAGE_TASK_SUBSCRIPTION_UNSUPPORTED。

异步生图 ​

提交任务 ​

查询任务 ​

取消任务 ​

计费行为 ​

异步生图

提交任务

查询任务

取消任务

计费行为