异步模式

异步模式会立即返回任务 ID，之后你在结果就绪时轮询获取。不带任何查询参数调用 API 时，默认就是这种行为。

前置条件

请先准备好 API Key。配置方式见 API 入门。

第一步：提交任务

发送 POST 请求发起一次生成任务：

cURL

curl -X POST "https://api.get3w.com/v1/google/nano-banana-pro/text-to-image" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A sunset over mountains",
    "aspect_ratio": "16:9",
    "resolution": "1k",
    "output_format": "png",
    "channel": "stable"
  }'

Python

import requests

response = requests.post(
    "https://api.get3w.com/v1/google/nano-banana-pro/text-to-image",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "A sunset over mountains",
        "aspect_ratio": "16:9",
        "resolution": "1k",
        "output_format": "png",
        "channel": "stable"
    }
)

task = response.json()
print(task["id"])  # Save this for polling

JavaScript

const apiKey = "YOUR_API_KEY";

const response = await fetch(
    "https://api.get3w.com/v1/google/nano-banana-pro/text-to-image",
    {
        method: "POST",
        headers: {
            "Authorization": `Bearer ${apiKey}`,
            "Content-Type": "application/json"
        },
        body: JSON.stringify({
            prompt: "A sunset over mountains",
            aspect_ratio: "16:9",
            resolution: "1k",
            output_format: "png",
            channel: "stable"
        })
    }
);

const task = await response.json();
console.log(task.id);  // Save this for polling

响应示例：

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "created",
  "estimated_duration": 52
}

请保存 id —— 后续获取结果需要用到。

第二步：轮询结果

用任务 ID 查询状态，直到进入终态（completed 或 failed）：

cURL

curl "https://api.get3w.com/v1/requests/${request_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

import time
import requests

task_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"  # From Step 1 response

while True:
    response = requests.get(
        f"https://api.get3w.com/v1/requests/{task_id}",
        headers={"Authorization": "Bearer YOUR_API_KEY"}
    )
    data = response.json()

    if data["status"] == "completed":
        print("Done!", data["outputs"])
        break
    elif data["status"] == "failed":
        print("Failed:", data["error"])
        break

    time.sleep(3)

JavaScript

const apiKey = "YOUR_API_KEY";
const taskId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"; // From Step 1

async function pollResult() {
    while (true) {
        const response = await fetch(
            `https://api.get3w.com/v1/requests/${taskId}`,
            { headers: { "Authorization": `Bearer ${apiKey}` } }
        );
        const data = await response.json();

        if (data.status === "completed") {
            console.log("Done!", data.outputs);
            return data;
        } else if (data.status === "failed") {
            console.error("Failed:", data.error);
            throw new Error(data.error);
        }

        await new Promise(r => setTimeout(r, 3000));
    }
}

pollResult();

响应示例（已完成）：

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "model": "google/nano-banana-pro/text-to-image",
  "status": "completed",
  "code": 0,
  "outputs": [
    "https://storage.example.com/output.png"
  ],
  "timings": {
    "queue_wait": 427,
    "celery_init": 2429,
    "api_call": 21392,
    "save": 1781,
    "run_overhead": 679,
    "total": 26709
  },
  "error": null,
  "created_at": "2026-03-28T07:51:34"
}

什么时候用异步模式

• 耗时较长的任务 —— 视频生成可能需要几分钟，避免长时间占用连接
• 批量处理 —— 一次提交大量任务，之后统一收集结果
• 更健壮的集成 —— 即使客户端断开，任务仍会继续执行，结果依然可取

轮询建议

• 用提交响应里的 estimated_duration 决定首次轮询前的等待时间
• 多数任务每 3–5 秒轮询一次即可
• 对超出预期耗时的任务使用指数退避

下一步

• 同步模式 — 快速任务的更简单方案
• Webhook 模式 — 通过回调接收结果，无需轮询