图片异步任务

APIPool 把支持的图片模型请求作为异步任务运行。提交接口立即返回任务 ID，之后由应用轮询这个任务，直到它结束。

图片模型与协议

下表列出的图片系列都使用异步任务。Key 所属分组决定可用模型与计费，不在请求体中传分组。

系列与调用 ID	分组	生成 / 参考图编辑	调用示例
`gpt-image-2`	官方、特惠	JSON 生成；文件上传编辑	官方、特惠
`gpt-image-2.5-flare`、`gpt-image-2.5-sunburst`	官方	JSON 生成；URL 参考图或文件上传编辑	GPT Image 2.5
`gemini-2.5-flash-image-preview`、`gemini-3.1-flash-image-preview`、`gemini-3-pro-image-preview`	官方、特惠	JSON 生成；URL 参考图或文件上传编辑	Gemini 图片
`seedream-4-0`、`seedream-4-5`、`seedream-5-0-lite`、`seedream-5-0-pro`	官方	JSON 生成；URL 参考图或文件上传编辑	Seedream
`qwen-image-2.0`、`qwen-image-2.0-pro`、`qwen-image-3.0`、`qwen-image-3.0-pro`	官方	JSON 生成；URL 参考图或文件上传编辑	Qwen Image
`z-image-turbo`	官方	仅 JSON 文生图	Alibaba 图片
`wan2.7-image`、`wan2.7-image-pro`	官方	JSON 生成；同接口 `image_urls` 编辑，未开放 multipart 编辑	Alibaba 图片

协议是 Images 请求格式 + APIPool 异步任务，不是 OpenAI 同步 Images 的响应格式。这些独立图片型号不应直接替换到 Chat Completions / Responses 的文字请求里；本站不支持通过这些端点生成图片，也没有开放 Gemini 原生生图入口。 GPT 文字模型通过 Responses 调用生图工具属于另一种调用方式，不在本页范围内。

提交任务

生成与已支持的文件编辑使用同一套任务流程；各模型的编辑方式以上表为准：

操作	请求
生成图片	以 JSON 调用 `POST /v1/images/generations`
编辑上传图片	以 `multipart/form-data` 调用 `POST /v1/images/edits`

提交成功返回 202 Accepted。保存响应体里的 id，或者 Location header 中的任务地址。

HTTP/1.1 202 Accepted
Location: /v1/tasks/imgtask_01...
X-APIPool-Task-Id: imgtask_01...
Content-Type: application/json

{
  "id": "imgtask_01...",
  "object": "image_generation.task",
  "status": "submitted",
  "model": "gpt-image-2",
  "created_at": 1787068800
}

submission_unknown 表示提交结果尚未确认。保留任务 ID 并继续轮询，不要重复提交同一个请求。

Seedream 参数

完整生成和编辑示例见 Seedream 图片 API。

Seedream 使用生成接口的 image_urls 传入参考图。例如 5.0 Pro 的多参考图请求：

{
  "model": "seedream-5-0-pro",
  "prompt": "把图 1 的人物放入图 2 的场景，并统一黄昏光线",
  "image_urls": [
    "https://example.com/person.jpg",
    "https://example.com/scene.jpg"
  ],
  "resolution": "1.5K",
  "size": "16:9"
}

模型	数量与参考图	分辨率
`seedream-4-0` / `seedream-4-5`	`n=1..15`，参考图数加 `n` 不超过 15；无参考图时 `n=1`	以模型支持范围为准
`seedream-5-0-lite`	原生 `n=1..15`，参考图数加 `n` 不超过 15	以模型支持范围为准
`seedream-5-0-pro`	固定 `n=1`，最多 10 张参考图	1K、1.5K、2K，或有效的 `WIDTHxHEIGHT` 精确像素；缺省为 1K

5.0 Pro 的第一张参考图不附加费用，第 2 张起逐张计费，最终价格在模型与价格展示。Seedream 不接受蒙版、stream: true、tools 或显式连续生成参数；暂不支持 layer_decomposition: true。

查询任务

在同一个 Base URL 上 GET 返回的 Location：

APIPOOL_ENDPOINT="https://app.apipool.dev"
TASK_ID="imgtask_01..."

curl "$APIPOOL_ENDPOINT/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $APIPOOL_API_KEY"

必须用提交任务时的同一个 API Key。即使两个 Key 属于同一个账户，用另一个 Key 查询也会返回 404。

状态值

状态	含义	客户端处理
`submission_unknown`	正在确认提交结果	继续轮询
`submitted`	任务已受理	继续轮询
`processing`	正在生成或编辑图片	继续轮询
`meter_pending`	已有输出，正在确认计费数据	继续轮询
`completed`	结果就绪	读取并下载 `data`
`failed`	任务失败	读取 `error`；不会再产生结果

任务未结束时请用有界的轮询间隔，例如每 2 秒查一次，长任务可以逐步拉长间隔。图片接口不支持用 stream: true 获取任务进度。

Python：提交并轮询

下面是独立的完整示例，使用 Python 3 标准库，无需 SDK。先设置 APIPOOL_API_KEY；运行会提交一条真实图片生成请求。若已有任务，设置 APIPOOL_TASK_ID 为之前保存的 ID，即可只查询，不再提交。请勿在执行前面的 curl 提交后又运行默认提交模式来查询，否则会创建第二个任务。

import json
import os
import time
from urllib.parse import quote
from urllib.request import Request, urlopen

base = "https://app.apipool.dev"
key = os.environ["APIPOOL_API_KEY"]

def request(path, payload=None):
    headers = {
        "Authorization": f"Bearer {key}",
        "User-Agent": "APIPool-Image-Example/1.0",
    }
    data = None
    if payload is not None:
        headers["Content-Type"] = "application/json"
        data = json.dumps(payload).encode()
    req = Request(base + path, headers=headers, data=data)
    with urlopen(req, timeout=60) as response:
        return response.status, json.load(response)

task_id = os.environ.get("APIPOOL_TASK_ID")
if not task_id:
    status, task = request("/v1/images/generations", {
        "model": "gemini-3.1-flash-image-preview",
        "prompt": "A blue ceramic cup on a white table",
        "size": "1:1",
        "resolution": "1K",
        "n": 1,
    })
    if status != 202 or not task.get("id"):
        raise SystemExit(f"Unexpected submission response: {status} {task}")
    task_id = task["id"]

print(f"APIPOOL_TASK_ID={task_id}", flush=True)
pending = {"submission_unknown", "submitted", "processing", "meter_pending"}
for _ in range(120):
    _, task = request("/v1/tasks/" + quote(task_id, safe=""))
    state = task.get("status")
    if state == "completed":
        for item in task["data"]:
            print(item["url"])
        break
    if state == "failed":
        raise SystemExit(json.dumps(task.get("error"), ensure_ascii=False))
    if state not in pending:
        raise SystemExit(f"Unknown task state: {state}; keep {task_id}")
    time.sleep(2)
else:
    raise SystemExit(f"Still pending. Resume with APIPOOL_TASK_ID={task_id}")

本例最多查询 120 次；退出不代表任务被取消。保留打印的任务 ID，稍后用同一 Key 继续查询。查询遇到网络错误或可重试 HTTP 状态时，也应恢复查询已有任务，不重新生成。提交超时且未取得任务 ID 时，不要自动重放提交；先核对任务记录或联系支持。修改模型时须同时按对应文档调整参数，不能仅替换任意模型名称。

完成结果

{
  "id": "imgtask_01...",
  "object": "image_generation.task",
  "status": "completed",
  "model": "gpt-image-2",
  "created_at": 1787068800,
  "completed_at": 1787068842,
  "data": [
    {
      "url": "https://objects.example/results/0.png?...",
      "expires_at": 1787072442
    }
  ],
  "result_expires_at": 1787155242
}

每个 data[].url 都是临时签名下载地址，expires_at 是它的 Unix 过期时间，请在过期前下载。结果本身保留到 result_expires_at；下载地址临近过期时，再查一次已完成的任务就能拿到刷新后的地址。

按 token 定价的图片模型会在完成响应中带上标准化的 usage。按张定价的模型按实际成功交付的图片数量及提交时选定的规格结算，不依赖 token usage。

失败结果

{
  "id": "imgtask_01...",
  "object": "image_generation.task",
  "status": "failed",
  "model": "gpt-image-2",
  "created_at": 1787068800,
  "completed_at": 1787068842,
  "error": {
    "code": "task_failed",
    "message": "Image generation task failed."
  }
}

可重试响应

提交返回 503 upstream_unavailable 表示服务暂未就绪。按响应中的 Retry-After 等待后重试；若已取得任务 ID，则继续查询原任务。
刷新临时下载地址失败时，查询已完成任务可能返回 503 result_url_refresh_failed。按 Retry-After 重试查询，不要重新提交图片请求。
429 concurrency_limit_exceeded 表示账户当前进行中的请求过多，按响应里的 Retry-After 延迟重试。

各分组的模型参数与计费说明：

图片异步任务

On this page