# 视频生成（按秒计费模型）

> 用 POST /v1/videos 创建图生视频、首尾帧、参考图、数字人和视频工具任务，查询状态、下载结果，按输出秒数计费。

网页版: https://bigmodel.io/zh-cn/docs/video-generation · 更新于 2026-10-18

[模型目录 → 视频](https://bigmodel.io/zh-cn/models?type=Video) 中的视频模型通过 `POST /v1/videos` 以异步任务运行，按输出视频的秒数计费。流程是：创建任务、查询状态、下载文件。失败和取消的任务不收费。

| 步骤 | 请求 |
|---|---|
| 预估价格（可选） | `POST /v1/videos`，带 `"dry_run": true` |
| 创建任务 | `POST /v1/videos` |
| 查询状态 | `GET /v1/videos/{id}` |
| 下载 | `GET /v1/videos/{id}/content` |
| 取消 | `POST /v1/videos/{id}/cancel` |


## 输入

图片、视频、音频输入可以是公开的 `https://` 链接，或 base64 data URI（`data:image/png;base64,...`），单个文件不超过 50 MB，整个请求体不超过 80 MB。

**视频模型需要首帧。** 用 `image` 传入。如果只有文字创意，先用[图片模型](https://bigmodel.io/zh-cn/docs/image-generation)生成首帧，再传入它的链接。只有文字的请求会返回 `400`，提示 “image is required”。

## 创建任务

```bash [cURL]
curl https://bigmodel.io/v1/videos \
  -H "Authorization: Bearer $BIGMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lantern-take-1" \
  -d '{
    "model": "seedance-2.0-fast",
    "prompt": "灯笼缓缓向右漂去，湖面薄雾流动",
    "image": "https://example.com/lantern.png",
    "seconds": 5,
    "resolution": "720p"
  }'
```

```python [Python]
import os, time, requests

BASE = "https://bigmodel.io/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['BIGMODEL_API_KEY']}"}

task = requests.post(f"{BASE}/videos", headers={**HEADERS, "Idempotency-Key": "lantern-take-1"}, json={
    "model": "seedance-2.0-fast",
    "prompt": "灯笼缓缓向右漂去，湖面薄雾流动",
    "image": "https://example.com/lantern.png",
    "seconds": 5,
}).json()

while task["status"] in ("queued", "running"):
    time.sleep(10)
    task = requests.get(f"{BASE}/videos/{task['id']}", headers=HEADERS).json()

print(task["status"], task.get("output", {}).get("url"), task.get("cost_usd"))
```

任务受理后返回 `202`、`Location` 响应头和：

```json
{"id": "6f1c...", "object": "video", "model": "seedance-2.0-fast", "status": "queued", "created_at": 1760000000, "estimated_cost_usd": 0.4272}
```

### 视频模型字段

| 字段 | 说明 |
|---|---|
| `model` | 必填。 |
| `prompt` | 画面里发生什么。 |
| `image` | 必填，首帧。也可写作 `first_frame`。 |
| `last_frame` | 可选，尾帧，仅支持首尾帧的模型可用，需同时传 `image`。 |
| `reference_images`、`reference_videos`、`reference_audios` | 参考素材数组，仅支持参考输入的模型可用。带参考素材时，`image` 也算作一张参考图。 |
| `seconds` | 输出时长（也可写作 `duration`）。默认 5 秒，并限制在模型支持的范围内。 |
| `resolution` | 模型支持的分辨率之一，如 `720p`。模型支持 `720p` 时默认 `720p`。 |
| `aspect_ratio` | 如 `16:9`、`9:16`。传 `size`（如 `1280x720`）也能设定比例。 |
| `audio` | 支持原生音频的模型可传 `true` 或 `false`。 |
| `seed` | 整数，模型支持时可复现结果。 |

每个模型的时长范围、分辨率和参考素材上限见[模型目录](https://bigmodel.io/zh-cn/models?type=Video)。超出范围会返回 `400`，并列出允许的取值。

### 数字人与视频工具

同一个接口也运行数字人和工具模型：

| 模型 | 输入 |
|---|---|
| `infinitetalk` | `image`（人像）或 `video`（单人视频），再加 `input_audio`（配音） |
| `latentsync`、`latentsync-music` | `video`（单人、露脸）和 `input_audio` |
| `wan-animate-2` | `image`（人物）、`video`（要模仿的动作），或两者都传 |
| `video-upscale`、`seedvr2-upscale` | `video`；`video-upscale` 可传 `target_resolution`：`1080p`（默认）或 `2k` |
| `video-to-clay` | `video`；`mode` 为 `clay_masked`（默认）、`clay` 或 `sculpt`；`keep_audio` |

数字人模型按配音（或视频）时长计费，工具模型按输入视频时长计费。

## 先预估价格

在同样的请求体里加 `"dry_run": true`。不会生成，也不会扣费；输入素材仍会被读取，以便按时长估价。

```bash
curl https://bigmodel.io/v1/videos \
  -H "Authorization: Bearer $BIGMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "seedance-2.0-fast", "image": "https://example.com/lantern.png", "seconds": 5, "dry_run": true}'
```

```json
{"object": "quote", "model": "seedance-2.0-fast", "unit": "per_second", "estimated_units": 5, "estimated_cost_usd": 0.4272}
```

## 用 Idempotency-Key 安全重试

创建任务时带上 `Idempotency-Key` 请求头（最多 200 个字符）。如果响应丢失，用同一个 Key 和同一个 API Key 重新发送，会拿回原来的任务，不会再生成一次。每个新视频使用新的 Key。

## 查询状态与下载

```bash
curl https://bigmodel.io/v1/videos/TASK_ID \
  -H "Authorization: Bearer $BIGMODEL_API_KEY"

curl -L -o video.mp4 https://bigmodel.io/v1/videos/TASK_ID/content \
  -H "Authorization: Bearer $BIGMODEL_API_KEY"
```

`status` 依次为 `queued`、`running`，最终为 `succeeded`、`failed` 或 `canceled`。建议每 5–15 秒查询一次。运行中 `progress` 可能显示 0–100。成功的任务带有 `output: {"type": "video", "url": "...", "expires_in": 86400}` 和实际扣费 `cost_usd`；失败的任务带有 `error.message`。

`/content` 会 `302` 跳转到文件，`curl` 需加 `-L`。`output.url` 无需 API Key 即可访问，有效期 24 小时，每次查询状态都会返回新链接。需要长期保存请下载文件。同一账户下的任意 API Key 都能查询该任务。

`POST /v1/videos/TASK_ID/cancel` 请求停止生成，接口返回当前任务；若任务尚未完成，稍后会变为 `canceled`。3 小时内未完成的任务会以 `failed` 结束，不收费。

## 计费方式

创建任务时，余额需在扣除仍在运行的任务后足以覆盖本次预估。任务成功后按实际生成的视频扣费，因此 `cost_usd` 可能与 `estimated_cost_usd` 略有差异。扣费记录在[用量](https://bigmodel.io/usage)中。各模型价格见[定价](https://bigmodel.io/zh-cn/pricing)。

部分视频模型按输出分辨率定价（例如 Seedance 2.0 Fast 的 480p 和 720p 价格不同）。不传 `resolution` 时，模型支持 720p 就用 720p。每个模型页列有各分辨率的价格，`dry_run` 会按你传的分辨率报价。

## 验证配置

把预估示例中的首帧换成你自己的图片链接并发送。返回 `200` 报价即说明 Key 可以使用该模型。然后创建任务并查询到 `succeeded`。

## 常见问题排查

**400 “image is required”。** 视频模型需要首帧。传入 `image`；没有图片时先用[图片模型](https://bigmodel.io/zh-cn/docs/image-generation)生成。

**400 “seconds must be between …” 或 “resolution must be one of …”。** 取值超出模型限制，按提示或模型目录中的范围调整。

**400 “… could not be read”。** 输入链接不是公开的 `https://`，或 data URI 格式有误、超过 50 MB。

**402 `insufficient_balance`。** 余额扣除运行中任务后不足以覆盖预估，请到[充值](https://bigmodel.io/purchase)页面充值。

**403 `permission_error`。** Key 未分配分组，请在 [API Key](https://bigmodel.io/keys) 中设置分组。

**404 `model_not_available`。** 该模型不对这个 Key 开放，或应调用其他接口（语音和音乐使用 `/v1/audio/*`）。

**404 `not_found_error`。** 任务 ID 有误，或任务属于其他账户。

**`/content` 返回 409 `not_ready`。** 任务尚未成功，请继续查询。

**503 `api_error`。** 生成服务暂时不可用。用同一个 `Idempotency-Key` 重试。

## 相关文档

- [图片生成](https://bigmodel.io/zh-cn/docs/image-generation)：制作首帧。
- [语音合成](https://bigmodel.io/zh-cn/docs/text-to-speech)：为数字人模型准备配音。
- [音乐、音效与音频工具](https://bigmodel.io/zh-cn/docs/audio-generation)。