> ## 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.

# 视频 API 总览

> 受控开放的视频生成能力、任务流程和接入边界

Tapapi 的视频 API 已具备受控接入能力，适合在模型、价格和账号权限都确认后接入文生视频、图生视频或参考图视频任务。

<Warning>视频能力不是默认全量开放能力。生产调用前必须确认：控制台能看到对应模型、价格已发布、账号分组有权限，并且具体模型文档写清楚参数和计费规则。</Warning>

## 核心流程

视频生成通常不是同步返回文件，而是异步任务：

```text theme={null}
提交视频任务
  -> 返回 task_id / video id
  -> 轮询任务状态
  -> 任务完成后获取视频内容
  -> 业务侧自行转存
```

| 步骤      | 说明                        |
| ------- | ------------------------- |
| 提交任务    | 发送 prompt、模型名、时长、参考图等参数   |
| 记录任务 ID | 保存 `task_id`，后续轮询和对账都靠它   |
| 轮询状态    | 根据任务状态决定继续等待、失败处理或取结果     |
| 获取内容    | 任务完成后下载视频流或读取结果 URL       |
| 自行转存    | 视频 URL 可能有有效期，不建议长期依赖临时地址 |

## 接口口径

当前文档按两层口径说明：

| 口径               | 路径                                                                 | 建议                |
| ---------------- | ------------------------------------------------------------------ | ----------------- |
| OpenAI / Sora 兼容 | `/v1/videos`、`/v1/videos/{task_id}`、`/v1/videos/{task_id}/content` | 后续公开视频主路径优先按这一层沉淀 |
| Tapapi 任务兼容      | `/v1/video/generations`、`/v1/video/generations/{task_id}`          | 受控场景和供应商适配层使用     |
| 供应商兼容入口          | Kling、Jimeng 等兼容路径                                                 | 仅在模型文档明确要求时使用     |

<Note>视频 API 的交互式 API Reference 暂不在文档站公开展示。正文先保留受控接入说明，等公开视频模型、价格和权限稳定后再开放 playground。</Note>

两层接口的返回结构不完全相同：`/v1/videos` 更接近 OpenAI video object，`/v1/video/generations` 更接近内部任务对象。业务侧不要用同一个 parser 混读两套响应。

## 能力范围

| 能力               | 当前文档口径           |
| ---------------- | ---------------- |
| 文生视频             | 受控接入，先看控制台模型和价格  |
| 图生视频             | 受控接入，输入格式随模型变化   |
| 首尾帧 / 多参考图       | 模型私有能力，需模型页单独说明  |
| Remix / 基于已有视频生成 | 受控能力，不作为默认接入路径   |
| 视频内容代理           | 任务完成后可通过内容路径取视频流 |
| 失败返还             | 异步任务失败通常返还预扣额度   |

## 接入前检查

| 检查项       | 为什么重要                |
| --------- | -------------------- |
| 控制台是否可见模型 | 不可见就不要生产调用           |
| 价格是否发布    | 视频成本高，不能靠猜测上线        |
| 参数是否写清楚   | 不同模型的时长、比例、输入图字段差异很大 |
| 任务状态是否可轮询 | 业务侧必须能处理排队、生成中、失败和完成 |
| 输出是否可转存   | 临时 URL 或代理内容不能当长期素材库 |
| 失败计费是否确认  | 超时、取消、审核拒绝要有明确处理策略   |

## 必须保存的字段

| 字段                             | 用途                |
| ------------------------------ | ----------------- |
| `task_id` / `id`               | 查询任务、获取内容、客服排障和对账 |
| `model`                        | 定位模型、价格和渠道        |
| `status` / `progress`          | 前端展示和任务状态机        |
| `created_at` / `completed_at`  | 判断耗时和超时           |
| `error.code` / `error.message` | 判断是否重试、返还或转人工     |
| `X-Oneapi-Request-Id`          | 定位提交和查询请求         |

生产接入建议先看 [当前可用性](/video-generation/availability)，再分别阅读 [文生视频](/video-generation/text-to-video)、[图生视频](/video-generation/image-to-video) 和 [任务与输出](/video-generation/tasks-and-output)。