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

# 任务与输出

> 视频生成的异步任务、轮询、计费和视频内容获取

视频生成通常走异步任务：提交请求后先返回任务 ID，生成完成后再获取视频内容。

## 任务状态

| OpenAI 兼容状态   | 内部任务状态                 | 含义          |
| ------------- | ---------------------- | ----------- |
| `queued`      | `SUBMITTED` / `QUEUED` | 已提交或排队中     |
| `in_progress` | `IN_PROGRESS`          | 模型生成中       |
| `completed`   | `SUCCESS`              | 已完成，可获取视频   |
| `failed`      | `FAILURE`              | 生成失败，通常返还预扣 |
| `unknown`     | `UNKNOWN`              | 状态异常或暂未识别   |

不同兼容入口可能返回不同字段名，但业务侧应统一保存：`task_id`、`model`、`status`、`progress`、`created_at`、`completed_at`、`error`。

<Note>`/v1/videos/{task_id}` 返回 OpenAI video object 风格；`/v1/video/generations/{task_id}` 返回 Tapapi 任务兼容风格。两者状态含义可以统一到业务状态机，但响应字段不要混用。</Note>

## 轮询建议

| 阶段     | 建议                 |
| ------ | ------------------ |
| 刚提交    | 先等待 5-10 秒再第一次查询   |
| 排队中    | 10-20 秒查询一次，避免高频轮询 |
| 生成中    | 15-30 秒查询一次        |
| 超过预期时间 | 标记为待确认，不要无限等待      |
| 大批量任务  | 做队列限速和并发控制         |

示例：

```bash theme={null}
curl https://tapapi.ai/v1/videos/task_xxx \
  -H "Authorization: Bearer $TAPAPI_API_KEY"
```

可能返回：

```json theme={null}
{
  "id": "task_xxx",
  "object": "video",
  "model": "your-video-model",
  "status": "in_progress",
  "progress": 42,
  "seconds": "5"
}
```

## 获取视频内容

任务完成后，可以通过内容路径获取视频流：

```bash theme={null}
curl https://tapapi.ai/v1/videos/task_xxx/content \
  -H "Authorization: Bearer $TAPAPI_API_KEY" \
  -o output.mp4
```

业务侧建议立刻把视频转存到自己的对象存储，并记录：

```text theme={null}
task_id | model | status | output_url | saved_url | quota | created_at | completed_at | request_id
```

<Warning>视频生成成功后，如果你的下载、转存或 CDN 上传失败，通常不等于模型生成失败。对账时要区分“模型任务失败”和“业务保存失败”。</Warning>

## 计费与返还

视频任务可能先预扣，再按最终结果结算：

| 结果         | 计费口径                          |
| ---------- | ----------------------------- |
| 提交失败       | 通常不扣费，或退回预扣                   |
| 任务排队 / 生成中 | 可能已预扣，等最终状态结算                 |
| 任务成功       | 通常正常计费，可能按实际时长、尺寸或结果补扣 / 返还差额 |
| 任务失败       | 通常返还预扣                        |
| 成功后下载失败    | 通常仍按成功任务计费                    |

最终以控制台用量记录、任务日志和模型计费规则为准。

## 排障材料

提交视频问题时请带上：

* 账号和 API Key 名称
* 模型名
* 提交时间
* `task_id`
* 提交请求和查询请求的 `X-Oneapi-Request-Id`
* 查询接口返回的状态和错误
* 是否已获取 `/content`
* 控制台用量截图
* 业务侧保存失败日志（如有）