# 视频生成

> Videos：提交任务 → 查任务号 → 出片。按生成秒数计费，成功才扣费。
> 分组：模型接入
> 更新时间：2026-10-13
> 原文：https://www.chenra.com/docs/model-video

## 视频生成（Videos）

一句话：**提交任务 → 拿任务号 → 过一会儿查一次 → 出片**。

视频生成跟别的接口不一样，它要跑 1~5 分钟，没法在一个请求里干等。所以拆成两步：

步骤
接口
作用

① 提交
POST /videos/generations
立刻返回一个**任务号**（这时还没出片）

② 查询
GET /videos/generations/{任务号}
返回 processing（还在生成）/ succeeded（出片了）/ failed（失败）

**轮询不用你操心。** 你只要偶尔查一下任务号就行；就算你提交完就不管了，我们这边也有定时任务替你盯着上游，出了片照样给你算好账。

支持的模型见「模型清单」里标有「视频」的模型，例如 doubao-seedance-2-0-mini-260615（最便宜）、doubao-seedance-2-0-fast-260128、doubao-seedance-2-5-260628、wanx2.1-t2v-turbo。

### 图生视频（i2v）

在「提交」里多带一个 image_url（首帧图），就是图生视频：

curl https://api.chenra.com/api/relay/v1/videos/generations \
 -H "Authorization: Bearer sk-你的密钥" \
 -H "Content-Type: application/json" \
 -d '{
 "model": "doubao-seedance-2-0-mini-260615",
 "prompt": "镜头缓慢推进，画面自然流动",
 "image_url": "https://你的图片地址/cover.png",
 "duration": 5,
 "resolution": "480p"
 }'

- image_url 支持**公网图片地址**，也支持**本地图片的 base64**（data:image/png;base64,xxxx）。

- **豆包 Seedance**：不用换模型，同一个模型带上图就按图生视频走。

- **通义万相**：改用图生视频模型（如 wanx2.1-i2v-turbo），同样多带一个 image_url。

- 剩下的流程完全一样：拿任务号 → 查任务 → 出片。

### 计费怎么算

- 按**生成出来的视频秒数**计费：费用 = 视频秒数 × 模型单价（元/秒）。

- **只有成功出片才扣费**，失败不扣费。

- 时长由你请求里的 duration 决定（默认 5 秒）；分辨率越高单价越贵（480p 最便宜）。

### 怎么调用

#### ① 提交任务

curl https://api.chenra.com/api/relay/v1/videos/generations \
 -H "Authorization: Bearer sk-你的密钥" \
 -H "Content-Type: application/json" \
 -d '{
 "model": "doubao-seedance-2-0-mini-260615",
 "prompt": "一只橘猫在草地上打滚，阳光洒在草地上，镜头缓慢推进",
 "duration": 5,
 "resolution": "480p",
 "ratio": "16:9"
 }'

返回里拿 id，那就是任务号：

{ "id": "vt3deac03947bd7320f484ab0bedf9d985", "object": "video.generation", "status": "processing", "model": "doubao-seedance-2-0-mini-260615" }

#### ② 查任务（过几秒查一次）

curl https://api.chenra.com/api/relay/v1/videos/generations/vt3deac03947bd7320f484ab0bedf9d985 \
 -H "Authorization: Bearer sk-你的密钥"

出片后 data[0].url 就是视频地址，usage.seconds 是这次的计费秒数：

{
 "id": "vt3deac03947bd7320f484ab0bedf9d985",
 "status": "succeeded",
 "completed": 1791854144,
 "data": [{ "url": "https://.../xxxx.mp4" }],
 "usage": { "seconds": 5 }
}

#### ③ Python 轮询示例

import time, requests

BASE = "https://api.chenra.com/api/relay/v1"
HEAD = {"Authorization": "Bearer sk-你的密钥"}

task = requests.post(f"{BASE}/videos/generations", headers=HEAD, json={
 "model": "doubao-seedance-2-0-mini-260615",
 "prompt": "一只橘猫在草地上打滚",
 "duration": 5,
 "resolution": "480p",
}).json()

while True:
 r = requests.get(f"{BASE}/videos/generations/{task['id']}", headers=HEAD).json()
 if r["status"] == "succeeded":
 print("视频地址：", r["data"][0]["url"])
 break
 if r["status"] == "failed":
 raise RuntimeError(r["error"]["message"])
 time.sleep(5) # 5~10 秒查一次都行

**轮询建议**：5~10 秒查一次。查询很轻，也不会重复扣费（同一个任务只扣一次）。

### 常见问题

- **出片了但链接打不开？** 视频地址是上游的**临时链接**（大约 24 小时有效），请及时下载转存到自己的存储。

- **一直 processing？** 上游在排队，正常几分钟内出片。等太久可以到控制台「API Key 管理 → 调用日志」看这一笔的任务状态。

- **failed 怎么办？** 看 error.message，多数是提示词没过审核。**失败不扣费**，改一下提示词重提即可。

- **提示词怎么写？** 直接描述画面（主体 + 动作 + 环境 + 镜头）；分辨率/时长用请求参数传，不用写进提示词。

## 提交视频生成任务

`POST /videos/generations`

提交一次视频生成，立刻返回任务号（此时还没出片）。用返回的 id 去查询接口取结果。

### 请求参数

| 参数 | 类型 | 必填 | 说明 | 默认值 |
| --- | --- | --- | --- | --- |
| model | string | 是 | 视频模型标识（见「模型清单」里标有「视频」的模型） |  |
| prompt | string | 是 | 画面描述（主体 + 动作 + 环境 + 镜头） |  |
| duration | integer | 否 | 生成视频时长（秒），越长越贵 | 5 |
| resolution | string | 否 | 分辨率：480p / 720p（越高越贵） | 480p |
| ratio | string | 否 | 宽高比：16:9 / 9:16 / 1:1 等 | 16:9 |
| image_url | string | 否 | 图生视频时传首帧图：公网图片地址，或 data:image/png;base64,...（不传就是文生视频） |  |

### 请求示例

```bash
curl https://api.chenra.com/api/relay/v1/videos/generations \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-mini-260615",
    "prompt": "一只橘猫在草地上打滚，阳光洒在草地上，镜头缓慢推进",
    "duration": 5,
    "resolution": "480p",
    "ratio": "16:9"
  }'
```

### 响应示例

```json
{
  "id": "vt3deac03947bd7320f484ab0bedf9d985",
  "object": "video.generation",
  "created": 1791854000,
  "model": "doubao-seedance-2-0-mini-260615",
  "status": "processing"
}
```

### 错误码

| 错误码 | 说明 |
| --- | --- |
| 400 | 缺少 prompt 参数 / 该模型不支持视频生成 |
| 402 | 余额不足，请先充值 |
| 502 | 上游提交失败 |

## 查询视频生成任务

`GET /videos/generations/{id}`

按任务号查结果。status 为 processing 时继续过几秒再查；succeeded 时 data[0].url 就是视频地址。失败不扣费。

### 请求参数

| 参数 | 类型 | 必填 | 说明 | 默认值 |
| --- | --- | --- | --- | --- |
| id | string | 是 | 提交时返回的任务号（放在路径里） |  |

### 请求示例

```bash
curl https://api.chenra.com/api/relay/v1/videos/generations/vt3deac03947bd7320f484ab0bedf9d985 \
  -H "Authorization: Bearer sk-你的密钥"
```

### 响应示例

```json
{
  "id": "vt3deac03947bd7320f484ab0bedf9d985",
  "object": "video.generation",
  "status": "succeeded",
  "completed": 1791854144,
  "model": "doubao-seedance-2-0-mini-260615",
  "data": [{ "url": "https://.../xxxx.mp4" }],
  "usage": { "seconds": 5 }
}

// 处理中：
// { "status": "processing" }
// 失败：
// { "status": "failed", "error": { "message": "内容审核未通过" } }
```

### 错误码

| 错误码 | 说明 |
| --- | --- |
| 404 | 任务不存在（或不是你这把密钥提交的） |