异步任务
创建任务使用普通模型 API Token；查询任务和资源使用资源 API Key。Gemini 与 GPT-Image 共用 /v1/image/tasks，不需要 Gemini 专属任务端点。
bash
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="gemini-3.1-flash-image"创建生成任务
bash
curl -i -sS "$SUPERTOKEN_BASE_URL/v1/image/tasks" \
-H "Authorization: Bearer $SUPERTOKEN_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: gemini-order-20260728-001" \
-d '{
"model": "'"$IMAGE_MODEL"'",
"operation": "generation",
"input": {
"prompt": "雨夜霓虹街道的电影概念图"
},
"output": {
"count": 1,
"aspect_ratio": "16:9",
"resolution": "4K",
"quality": "auto",
"format": "png"
},
"provider_options": {
"google": {
"generationConfig": {
"temperature": 0.8
}
}
},
"client_reference_id": "order-20260728-001"
}'成功返回 202 Accepted、Location 和任务对象。相同用户使用相同 Idempotency-Key 与相同规范化请求重试时会返回原任务；内容不同时返回 409。
创建编辑任务
URL 编辑使用 input.images[].url，不要提交 input.mask：
bash
curl -sS "$SUPERTOKEN_BASE_URL/v1/image/tasks" \
-H "Authorization: Bearer $SUPERTOKEN_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3-pro-image-count",
"operation": "edit",
"input": {
"prompt": "保留商品主体，把背景改成自然光摄影棚",
"images": [
{"url": "https://img.example.com/reference.png"}
]
},
"output": {
"count": 1,
"aspect_ratio": "1:1",
"resolution": "2K",
"quality": "auto",
"format": "png"
}
}' | jq .本地文件可以直接使用 multipart：
bash
curl -sS "$SUPERTOKEN_BASE_URL/v1/image/tasks" \
-H "Authorization: Bearer $SUPERTOKEN_KEY" \
-H "Idempotency-Key: gemini-edit-20260728-001" \
-F "model=$IMAGE_MODEL" \
-F "operation=edit" \
-F "prompt=保留主体，把背景改成白色摄影棚" \
-F "image=@./reference.png" \
-F "n=1" \
-F "aspect_ratio=4:3" \
-F "resolution=2K" \
-F "quality=auto" \
-F "output_format=png" | jq .查询任务
bash
export TASK_ID="task_example123"
curl -sS "$SUPERTOKEN_BASE_URL/v1/image/tasks/$TASK_ID" \
-H "Authorization: Bearer $RESOURCE_API_KEY" | jq .| 状态 | 含义 |
|---|---|
queued | 等待执行 |
in_progress | 正在调用 Gemini 并归档结果 |
succeeded | 从 result.images[] 读取 URL 与资源 ID |
failed | 从 error 读取稳定错误码与可重试标记 |
当终态错误的 error.code 为字符串 "524" 时，表示内部图片服务暂时不可用，且 retryable 为 true。重新创建任务时必须使用新的 Idempotency-Key；复用原 Key 只会返回原失败任务。
成功任务的 result.images[] 始终使用 URL。Gemini 上游返回 URL 时原样使用；返回 inlineData.data 时由执行节点验证后上传对象存储。生成资源同时进入 /v1/assets。
Usage 与终态结算
任务查询、Webhook 和消费日志使用同一份归一化 usage。按量模型在成功终态根据实际 Token 结算，多退少补；失败终态退回预扣额度。重复回调不会重复扣费。