# 异步任务
> Agent 任务生命周期、Task envelope、轮询、回调与取消。

耗时超过一次 HTTP 往返的 Agent skills 会返回 `202` + Task envelope。
任务进入队列异步执行，可以通过轮询或回调观察：

```text
queued → running → succeeded | failed | canceled
```

## Task envelope

创建响应、`GET /v1/tasks/{task_id}`、回调 POST body 三处返回**同一结构**：

| 字段 | 说明 |
| --- | --- |
| `task_id` | `task_` 前缀的任务 ID；幂等重试返回同一 ID |
| `status` | `queued / running / succeeded / failed / canceled` |
| `capability` | 能力名，如 `text_to_video` 或 `social_data_fetch` |
| `workload_type` | 媒体/理解为 `model`，公开社交数据读取为 `social_operation` |
| `model` / `resolved_model` | 请求的模型（可为 `auto`）/ 实际执行的模型。`social_operation` 任务为 null |
| `social` | 社交 Task 上出现：`platform`、`operation_key`、`operation_name`、`schema_hash` |
| `input` | 规范化后的输入回显 |
| `output` | 产物，仅 `succeeded` 时存在；结构见各能力页 |
| `progress` | `{ percent, stage, message }`，仅运行中有意义 |
| `warnings[]` | 保留字段；当前恒为空列表 |
| `error` | `{ code, message, retryable }`，仅 `failed` 时存在 |
| `usage` / `billing` | 计费明细 → [计费与用量](https://docs.beatra.ai/zh/docs/mechanisms/billing) |
| `callback` | 回调投递状态 → [回调](https://docs.beatra.ai/zh/docs/mechanisms/callbacks) |
| `metadata` | 保留字段；创建时接受，当前响应中恒为 `null` |
| `created_at / started_at / completed_at` | 生命周期时间戳（UTC） |
| `links` | `{ self, cancel }` |

## 轮询、列表与取消

| 操作 | 端点 | 说明 |
| --- | --- | --- |
| 查单个 | `GET /v1/tasks/{task_id}` | 返回完整 envelope；建议 5s 间隔轮询至终态 |
| 列表 | `GET /v1/tasks?limit=100` | 游标分页摘要，**不含** output/usage |
| 取消 | `POST /v1/tasks/{task_id}/cancel` | 幂等；已终态任务原样返回，执行中的任务仅在停止得到确认后才会取消成功 |

远程执行开始前，取消会停止任务并退回预付积分。执行开始后，只有在停止得到确认时，Beatra 才返回 `canceled`。`409` 表示任务仍在继续：不要声称任务已停止或承诺退款，不要提交替代任务，并继续轮询同一个任务直到终态。

MiniMax H3 仅能在上游任务仍为 `queued` 时确认取消。任务进入 `running` 后，
Beatra 返回 `409` 且不退款；此时不会调用上游 DELETE，因为它不能代表一次
已确认的取消。

## 显式模型 vs `auto`

- 显式指定的 `model` **绝不会被悄悄替换**：它不支持某个参数时，请求立即以
  `422 unsupported_option` 失败并指明字段。
- `model: "auto"` 时，选择与切换具体模型本就是平台的职责；终态任务的
  `resolved_model` 记录实际执行的模型。

公开社交数据任务与创作一样预付费：一次 `beatra.social.execute` 只创建一条任务、只做一次查询。查询开始后取消会返回 `409`，继续轮询同一条任务。

## 产物取回较慢时

模型完成后，Beatra 要先从上游下载生成的文件并保存，任务才会成功；这期间 `progress.stage` 为 `finalizing`。如果上游的文件服务持续出错，Beatra 会在最长约 40 分钟内再试几轮，不会重新生成，也不会重复扣费，任务在此期间保持 `running`。仍然取不回时，任务以 `model_output_invalid` 失败并退还积分。请继续轮询同一个任务：再次提交会新建一个单独计费的任务。

## 产物保存

`output` 里的资源 URL 为 CDN 地址，**请在拿到结果后及时转存**到自己的存储，不要把它当永久链接。