# 生成视频

视频是异步任务：**提交一次，保存ID，查询同一任务，成功后下载。** 不要通过重复提交来“刷新进度”。

![异步视频任务的提交、等待、下载和异常处理示意](/docs/assets/video-flow.svg)

## 模型与参数

以下范围按本站现有视频插件1.0.2核对；有权限不等于实时有容量。

| 完整模型名 | resolution | 整数时长seconds |
| --- | --- | --- |
| `doubao-seedance-2-0` | `720p` / `1080p` / `4k` | 4–15 |
| `doubao-seedance-2-0-fast` | `720p` | 4–15 |
| `doubao-seedance-2-0-mini` | `720p` | 4–15 |
| `doubao-seedance-2-5` | `720p` / `1080p` | 4–30 |
| `MiniMax-H3` | `720p` / `1080p` / `2k` / `4k` | 5–15 |
| `MiniMax-H3-Fast` | `720p` / `1080p` / `2k` / `4k` | 5–15 |

使用对应视频分组的密钥。`ratio`支持`adaptive`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`。大小写及完整模型名按表填写。

## 1 提交任务

将以下内容保存为`video.json`：

```json
{
  "model": "doubao-seedance-2-0",
  "prompt": "一只橘猫缓慢走过洒满阳光的窗台，镜头平稳，无文字",
  "seconds": 4,
  "resolution": "720p",
  "ratio": "16:9"
}
```

下载 [request.py](/docs/examples/request.py)，执行一次：

```sh
python3 request.py /v1/videos --json video.json --allow-charge --out video-task.json
```

提交成功后，从结果中保存`id`（部分响应使用`task_id`）。这是之后查询和下载要用的客户端任务ID，不要从其他平台复制一个任务号替代。

若没有取得任务ID或提交超时，记录请求ID和时间，先查本站任务/账单或联系客服，不立刻重提。即使程序没有拿到响应，服务端也可能已经接单。

## 2 查询同一个任务

把`TASK_ID`替换为刚才获得的ID：

```sh
python3 request.py /v1/videos/TASK_ID
```

`queued`、`pending`、`in_progress`、`processing`或`running`表示尚未完成；`completed`或`succeeded`表示成功；`failed`或`cancelled`表示终态失败。遇到陌生状态先保留，不按成功处理。

手动或程序每隔约10–30秒查一次即可；这个间隔是客户端建议，不是服务的频率上限承诺。可以稍后继续查同一ID，不需要始终开着提交窗口。多分钟等待并不罕见，不能把固定30秒当作失败界限。

## 3 成功后下载

```sh
python3 request.py /v1/videos/TASK_ID/content --out video.mp4
```

使用同一密钥从本站内容接口获取视频。检查文件可播放、时长及尺寸，再确认任务完成。不要把密钥发到第三方下载地址。

## 参考图与暂不支持的参数

本站插件接受JSON请求，参考图使用可访问的HTTPS URL放在`image`或`images`字段；不是直接提交本机文件路径，也不是multipart。仅使用你有权上传的非敏感图片。参考图字段的具体模型兼容性与数量限制须按当前模型说明确认，本页默认例子是文生视频。

**当前不接收参考视频字段**，包括`video`、`video_url`、`reference_video`等；不要凭别的平台文档照搬。其余高级metadata选项只在有明确模型说明时使用。

## 计费与异常

提交前先看[视频计费说明](./billing.md#视频)和模型广场。分辨率、秒数和模型都会影响价格；不要把普通Token目录价误当视频价。任务可能先预扣、后结算，失败/退款以账单和任务终态为准，不承诺所有网络错误立即退款。

历史样本曾有提交超时及较长等待。教程不承诺固定完成时间，也不自动重试可能已计费的提交。