异步任务

异步接口先返回任务对象，图片生成在后台继续执行。创建任务使用普通模型 API Token；查询任务和预上传图片使用资源 API Key。

提交成功后，控制台的“任务日志”会显示异步图片任务。你可以按任务 ID 或“图片”资源类型筛选，查看排队、生成中、成功或失败状态以及当前进度；任务成功后还可以在结果列预览或打开图片。生成资源会同时进入“资源管理中心 → 资源列表”，详见资源管理中心。

端点

能力	方法与路径	使用的密钥
创建任务	POST /v1/image/tasks	模型 API Token，sk-...
查询任务	GET /v1/image/tasks/{task_id}	资源 API Key，ak_...
列出任务	GET /v1/image/tasks	资源 API Key，ak_...
批量查询	POST /v1/image/tasks/query	资源 API Key，ak_...
multipart 预上传	POST /v1/image/uploads	资源 API Key，ak_...
Base64 预上传	POST /v1/image/uploads/base64	资源 API Key，ak_...

export SUPERTOKEN_BASE_URL="https://api.supertoken.cc"
export SUPERTOKEN_KEY="YOUR_MODEL_API_TOKEN"
export RESOURCE_API_KEY="YOUR_RESOURCE_API_KEY"
export IMAGE_MODEL="gpt-image-2"

创建任务

文生图任务

curl -i -sS "$SUPERTOKEN_BASE_URL/v1/image/tasks" \
  -H "Authorization: Bearer $SUPERTOKEN_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-20260722-001" \
  -d '{
    "model": "'"$IMAGE_MODEL"'",
    "operation": "generation",
    "input": {
      "prompt": "一张雨夜霓虹街道的电影概念图，广角构图"
    },
    "output": {
      "count": 1,
      "size": "1024x1024",
      "quality": "low",
      "format": "png"
    },
    "client_reference_id": "order-20260722-001"
  }'

成功创建返回 HTTP 202 Accepted，并带有任务查询位置和建议轮询间隔：

Location: /v1/image/tasks/task_example123
Retry-After: 2

{
  "id": "task_example123",
  "object": "image.task",
  "model": "gpt-image-2",
  "operation": "generation",
  "status": "queued",
  "progress": 0,
  "result": null,
  "usage": {},
  "error": null,
  "client_reference_id": "order-20260722-001",
  "created_at": 1784682000,
  "started_at": null,
  "completed_at": null,
  "updated_at": 1784682000
}

Idempotency-Key 可选，最长 128 个字符。相同用户使用同一个 Key 和相同请求内容重试时会返回原任务；同一个 Key 对应不同内容会返回 409 Conflict。

URL 编辑任务

异步 URL 编辑使用 input.images[].url，这与同步接口的顶层 image 字段不同：

jq -nc \
  --arg model "$IMAGE_MODEL" \
  --arg image1 "https://img.example.com/reference-1.png" \
  --arg image2 "https://img.example.com/reference-2.png" \
  '{
    model: $model,
    operation: "edit",
    input: {
      prompt: "融合两张参考图，保持主体比例和自然光影",
      images: [
        {url: $image1},
        {url: $image2}
      ]
    },
    output: {
      count: 1,
      size: "1024x1024",
      quality: "low",
      format: "png"
    }
  }' |
curl -sS "$SUPERTOKEN_BASE_URL/v1/image/tasks" \
  -H "Authorization: Bearer $SUPERTOKEN_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- | jq .

URL Mask 使用 input.mask.url：

{
  "input": {
    "prompt": "只修改 Mask 指定区域",
    "images": [{ "url": "https://img.example.com/source.png" }],
    "mask": { "url": "https://img.example.com/mask.png" }
  }
}

本地文件编辑任务

本地文件可直接使用 multipart 创建异步编辑任务：

curl -sS "$SUPERTOKEN_BASE_URL/v1/image/tasks" \
  -H "Authorization: Bearer $SUPERTOKEN_KEY" \
  -H "Idempotency-Key: edit-20260722-001" \
  -F "model=$IMAGE_MODEL" \
  -F "operation=edit" \
  -F "prompt=将两张参考图融合为自然的产品海报" \
  -F "image=@./reference-1.png" \
  -F "image=@./reference-2.png" \
  -F "size=1024x1024" \
  -F "quality=low" \
  -F "output_format=png" | jq .

需要局部编辑时，再增加一个 -F "mask=@./mask.png"。multipart 任务只能用于 operation=edit。

查询任务

export TASK_ID="task_example123"

curl -sS "$SUPERTOKEN_BASE_URL/v1/image/tasks/$TASK_ID" \
  -H "Authorization: Bearer $RESOURCE_API_KEY" | jq .

状态	含义	建议动作
queued	已进入队列	按 Retry-After 建议间隔继续查询
in_progress	正在生成	继续轮询，不要高频请求
succeeded	已完成	从 result.images[] 读取结果
failed	任务失败	查看 error.code、error.message 和 error.retryable

当终态错误的 error.code 为字符串 "524" 时，表示内部图片服务暂时不可用，且 retryable 为 true。若要重新创建任务，请使用新的 Idempotency-Key；复用原 Key 只会返回原来的失败任务。

成功任务的结果结构：

{
  "id": "task_example123",
  "object": "image.task",
  "model": "gpt-image-2",
  "operation": "generation",
  "status": "succeeded",
  "progress": 100,
  "result": {
    "images": [
      {
        "asset_id": "asset_example123",
        "url": "https://example.com/generated/image.png",
        "mime_type": "image/png",
        "format": "png",
        "width": 1024,
        "height": 1024,
        "size_bytes": 1843921,
        "filename": "image.png"
      }
    ]
  },
  "usage": {},
  "error": null,
  "created_at": 1784682000,
  "started_at": 1784682001,
  "completed_at": 1784682038,
  "updated_at": 1784682038
}

完整的 Python 和 Node.js 轮询程序见代码示例。不希望持续轮询时，可以启用 Webhook。

任务成功后，生成的图片也会出现在控制台的“资源管理中心 → 资源列表”。你可以按任务 ID、模型或时间筛选，预览结果、复制链接、打开图片或下载资源。需要通过 API 管理结果时，使用资源 API Key 调用 /v1/assets，详见资源管理中心。

列表与批量查询

按条件列出

curl -sS \
  "$SUPERTOKEN_BASE_URL/v1/image/tasks?status=succeeded&operation=generation&limit=20" \
  -H "Authorization: Bearer $RESOURCE_API_KEY" | jq .

批量查询

curl -sS "$SUPERTOKEN_BASE_URL/v1/image/tasks/query" \
  -H "Authorization: Bearer $RESOURCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task_ids": [
      "task_example123",
      "task_example456"
    ]
  }' | jq .

列表接口支持 status、operation、client_reference_id、created_after、created_before、after 和 limit。limit 默认为 20，范围为 1 到 100；批量查询一次最多传入 100 个任务 ID。

预上传图片

预上传适合需要把“准备图片”和“创建任务”拆成两个步骤的业务。返回的临时 URL 可直接用于 input.images[].url 和 input.mask.url，请尽快提交任务。

multipart 预上传

curl -sS "$SUPERTOKEN_BASE_URL/v1/image/uploads" \
  -H "Authorization: Bearer $RESOURCE_API_KEY" \
  -F "image=@./reference-1.png" \
  -F "image=@./reference-2.png" \
  -F "mask=@./mask.png" | jq .

响应中的 images 和 mask 可直接放入后续任务请求：

{
  "object": "image.upload.list",
  "data": [],
  "images": [
    "https://example.com/temporary/reference-1.png",
    "https://example.com/temporary/reference-2.png"
  ],
  "mask": "https://example.com/temporary/mask.png"
}

Base64 预上传

base64 < ./reference-1.png | tr -d '\n' |
jq -Rs '{images: [{b64_json: ., field: "image"}]}' |
curl -sS "$SUPERTOKEN_BASE_URL/v1/image/uploads/base64" \
  -H "Authorization: Bearer $RESOURCE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- | jq .

每个 Base64 项可使用纯字符串，或使用包含 b64_json、base64、data 之一的对象；内容也可以是完整的数据 URL。

下一步

• Webhook 完成通知
• 资源管理中心
• Python 与 Node.js 代码示例
• 参数与错误