> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 异步任务

> 任务生命周期、状态、优先级和保留期。

没有同步端点。查询 AI 引擎需要数秒到数分钟，因此每个请求都会成为一个持久化的队列任务，由你稍后获取。

## 生命周期

```mermaid theme={null}
stateDiagram-v2
    [*] --> QUEUED: POST /v1/async/task
    QUEUED --> PROCESSING: worker claims
    PROCESSING --> COMPLETED: engine answered
    PROCESSING --> FAILED: retries exhausted
    PROCESSING --> QUEUED: transient error, requeued
    COMPLETED --> [*]: polling expires after 24h
    FAILED --> [*]: polling expires after 24h
```

## 状态

<ResponseField name="QUEUED" type="status">
  已接受并持久化，正在等待 worker。
</ResponseField>

<ResponseField name="PROCESSING" type="status">
  某个 worker 持有该任务的租约，正在驱动引擎。
</ResponseField>

<ResponseField name="COMPLETED" type="status">
  终止状态。`response` 字段已填充。
</ResponseField>

<ResponseField name="FAILED" type="status">
  终止状态。`error` 字段给出原因。
</ResponseField>

遇到临时失败（引擎超时、临时错误）的任务会回到 `QUEUED` 并重试。只有重试耗尽后才会落定为 `FAILED`，因此
`PROCESSING → QUEUED` 的转换是正常的，无需告警。

## 优先级

`priority` 为兼容而保留，会原样出现在任务元数据中。取值 `1` 到 `10`，默认 `1`，超出范围的值会被截断到范围内，
而不是被拒绝。

```json theme={null}
{ "taskType": "GEMINI", "priority": 8, "payload": { "prompt": "..." } }
```

执行顺序不由优先级、提交时间或账户保证。对于有依赖的工作，请等前一个任务完成后再提交下一个。套餐并发限制
同时适用于排队中和处理中的任务。

## 保留期

终止状态的任务在**完成后 24 小时内**可通过公开轮询获取。之后，`GET /v1/async/task/{id}` 返回
`404 NOT_FOUND`，与从未存在的 id 相同。底层记录会永久保留；过期只限制公开轮询和手动 webhook 重放，
不限制存储。自动 webhook 重试独立继续进行。

如果你依赖轮询而不是 webhook，请在该窗口内尽早取回结果。

## 选择 webhook 还是轮询

优先使用 webhook。轮询是恢复路径。

| | Webhook | 轮询 |
| - | - | - |
| 获取结果的延迟 | 完成即推送 | 取决于轮询间隔 |
| API 负载 | 每个任务一次 POST | 每个任务每次轮询一次 GET |
| 需要公网端点 | 是 | 否 |
| 你方宕机时 | 重试约 30 分钟后放弃 | 24 小时内可取 |

健壮的客户端两者兼用：以 webhook 作为快速路径，对从未收到通知的任务在保留窗口关闭前通过轮询对账。