什么是任务

一次任务（task，在 API 中也称为 request）就是模型的一次运行。提交后会返回一个 ID，你用它来追踪这次运行。

生命周期

created → processing → completed | failed

状态	含义
created	已受理、已计价、已入队
processing	工作节点正在向上游供应商执行
completed	执行成功，outputs 已填充
failed	执行出错，code 和 error 说明原因

completed 和 failed 是终态 —— 一旦看到其中之一就停止轮询。供应商重试发生在单个任务内部，因此从上游失败中恢复的任务会保持同一个 ID，也不会表现为 failed。

提交响应

提交只返回一个极简的受理确认，而不是结果：

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

字段	说明
id	任务 ID，用于轮询或关联 webhook
status	这里恒为 created
estimated_duration	秒数，来自同模型同通道近期运行的耗时中位数。历史数据不足时为 null

加上 ?sync=true 可以跳过这一步，直接在同一次响应中拿到完整结果。

结果对象

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "model": "google/nano-banana-pro/text-to-image",
  "status": "completed",
  "code": 0,
  "input": {
    "prompt": "A cat wearing a space suit",
    "aspect_ratio": "16:9"
  },
  "outputs": ["https://storage.example.com/output.png"],
  "timings": {
    "queue_wait": 427,
    "celery_init": 2054,
    "api_call": 23068,
    "save": 1902,
    "run_overhead": 679,
    "total": 28131
  },
  "error": null,
  "created_at": "2026-03-28T07:50:42"
}

字段	说明
id	任务 ID
model	实际运行的模型 slug
status	当前状态
code	成功为 0，否则为任务错误码
input	你提交的参数
outputs	输出 URL 数组；非 completed 时为空
timings	各阶段耗时（毫秒）
error	错误信息，成功时为 null
created_at	任务创建时间

对于 speech-to-text，outputs 中存放的是转写文本，而不是 URL。

耗时明细

所有数值单位为毫秒：

阶段	衡量的内容
queue_wait	从提交到被工作节点取走之间的等待时间
celery_init	调用模型前的工作节点启动耗时
api_call	在上游供应商处消耗的时间
save	将输出持久化到存储的耗时
run_overhead	其余内部处理耗时
total	端到端总耗时

对比模型或通道时，api_call 才是关键指标 —— 其余部分属于平台开销。

获取任务结果

轮询

curl "https://api.get3w.com/v1/requests/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
  -H "Authorization: Bearer YOUR_API_KEY"

任务仍在执行时，你会得到一个精简响应，并附带 Retry-After: 3 响应头：

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "processing"
}

建议每 3–5 秒轮询一次。完整轮询循环见异步模式。

Webhook

提交时传入 ?webhook=<your-url>，任务完成后同样的结果体会以 POST 推送给你。详见如何使用 Webhook。

同步

提交时传入 ?sync=true，请求会阻塞到任务完成并直接返回结果。详见 API 入门。

数据保留

任务记录保留 7 天。存放在 Get3W 上的输出文件保留当月和上一个自然月，之后会被清除。由于这个窗口按整个自然月计算，月末创建的文件实际存活时间比月初创建的更短 —— 需要长期保留的内容请及时下载，不要依赖某个固定天数。

如果你为 API Key 绑定了自己的云存储，输出会写入你的存储，保留策略由你自己掌控。

失败与计费

任务在入队前会先计价并校验余额 —— 余额不足的请求会以 402 被拒绝且不会执行。费用在执行之后结算，因此从未到达供应商的任务不会产生模型调用费用。

下一步

• Get3W 工作原理 —— 请求流程与供应商路由
• 什么是账户等级 —— 等级如何影响任务价格
• 错误码 —— 每个 code 的含义