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

# 视频生成

> 创建异步视频任务，轮询直到完成，再下载产物。

视频是异步的。提交任务，轮询到终态，再读取 `outputs[].url`。

1. `POST /v2/videos` — 创建任务
2. `GET /v2/videos/{id}` — 查询状态
3. `status` 为 `completed` 时下载 `outputs[].url`
4. 可选：`DELETE /v2/videos/{id}` — 取消进行中的任务

公开任务 ID 形如 `gen-...`。查询和取消会固定回到创建该任务的平台。

## 支持的 V2 模型

以下四款模型统一使用 `POST /v2/videos`，查询和取消使用 `/v2/videos/{id}`。模型名必须按表填写；“Flash”对应这里的 Fast。

| 模型 | 请求中的 `model` | 时长 | 分辨率 | 当前输入范围 |
| - | - | - | - | - |
| Seedance 2.0 Mini | `doubao-seedance-2-0-mini-260615` | 4–15 秒 | 480p、720p | 文本、图片、视频和音频参考 |
| Seedance 2.0 | `seedance-2.0` | 4–15 秒 | 480p、720p | 文本、图片 |
| Seedance 2.0 Fast | `doubao-seedance-2-0-fast-260128` | 4–15 秒 | 480p、720p | 文本、图片 |
| Seedance 2.5 | `doubao-seedance-2-5-260628` | 4–30 秒 | 480p、720p、1080p | 文本、图片 |

默认参数均为 `duration: 5`、`resolution: "480p"`、`aspect_ratio: "16:9"`、`audio: false`。标准版、Fast 和 2.5 最多接受 9 张图片，不接受视频或音频参考。四款模型均不开放 `provider_options`。这是 PipeLLM 当前开放范围，不能直接套用上游的全部能力。

## 创建任务

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl https://api.pipellm.ai/v2/videos \
    -H "Authorization: Bearer $PIPELLM_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "seedance-2-0-mini",
      "prompt": "一只金毛在日出时分沿着湿沙滩奔跑",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "480p",
      "audio": false
    }'
  ```

  ```python Python theme={"dark"}
  import os
  import time
  import requests

  headers = {
      "Authorization": f"Bearer {os.environ['PIPELLM_API_KEY']}",
      "Content-Type": "application/json",
  }

  created = requests.post(
      "https://api.pipellm.ai/v2/videos",
      headers=headers,
      json={
          "model": "seedance-2-0-mini",
          "prompt": "一只金毛在日出时分沿着湿沙滩奔跑",
          "duration": 5,
          "aspect_ratio": "16:9",
          "resolution": "480p",
          "audio": False,
      },
  )
  created.raise_for_status()
  task = created.json()
  task_id = task["id"]

  while True:
      poll = requests.get(
          f"https://api.pipellm.ai/v2/videos/{task_id}",
          headers=headers,
      )
      poll.raise_for_status()
      task = poll.json()
      status = task["status"]
      print(status, task.get("progress"))
      if status in {"completed", "failed", "cancelled", "expired"}:
          break
      time.sleep(5)

  if task["status"] == "completed":
      print(task["outputs"][0]["url"])
  else:
      print(task.get("error"))
  ```

  ```typescript TypeScript theme={"dark"}
  const headers = {
    Authorization: `Bearer ${process.env.PIPELLM_API_KEY}`,
    "Content-Type": "application/json",
  };

  const created = await fetch("https://api.pipellm.ai/v2/videos", {
    method: "POST",
    headers,
    body: JSON.stringify({
      model: "seedance-2-0-mini",
      prompt: "一只金毛在日出时分沿着湿沙滩奔跑",
      duration: 5,
      aspect_ratio: "16:9",
      resolution: "480p",
      audio: false,
    }),
  });
  const task = await created.json();
  let current = task;

  while (true) {
    const poll = await fetch(`https://api.pipellm.ai/v2/videos/${current.id}`, {
      headers,
    });
    current = await poll.json();
    console.log(current.status, current.progress);
    if (["completed", "failed", "cancelled", "expired"].includes(current.status)) {
      break;
    }
    await new Promise((resolve) => setTimeout(resolve, 5000));
  }

  if (current.status === "completed") {
    console.log(current.outputs[0].url);
  } else {
    console.error(current.error);
  }
  ```
</CodeGroup>

创建接口返回的任务信封与查询相同。任务完成前 `outputs` 为空。

## Seedance 2.0 Mini

| | |
| - | - |
| 公开名 | `seedance-2-0-mini` |
| 别名 | `seedance-2.0-mini`、`doubao-seedance-2-0-mini-260615` |
| 时长 | 4–15 秒（默认 `5`） |
| 分辨率 | `480p`、`720p`（默认 `480p`） |
| 画幅 | 默认 `16:9` |
| 音频 | 默认 `false` |
| 图片输入 | `type=image_url` 且 `role=reference_image`，最多 9 张 |
| 视频输入 | `type=video_url`，可选 `role=reference_video`，最多 3 个 |
| 音频输入 | `type=audio_url`，可选 `role=reference_audio`，最多 3 个 |
| 参考视频时长 | 单个 ≤ 15 秒；合计 ≤ 15 秒 |

该模型配置不支持 `provider_options`。未知 JSON 字段会被拒绝。

### 文生视频

```json theme={"dark"}
{
  "model": "seedance-2-0-mini",
  "prompt": "镜头缓慢扫过雨中的霓虹巷子",
  "duration": 5,
  "resolution": "480p"
}
```

### 参考图

```json theme={"dark"}
{
  "model": "seedance-2-0-mini",
  "prompt": "同一个角色走进森林",
  "inputs": [
    {
      "type": "image_url",
      "url": "https://example.com/character.png",
      "role": "reference_image"
    }
  ]
}
```

## 状态

| 状态 | 含义 |
| - | - |
| `queued` | 已接受，排队中 |
| `in_progress` | 正在生成 |
| `completed` | 完成，读取 `outputs` |
| `failed` | 失败，读取 `error` |
| `cancelled` | 已被 `DELETE` 取消 |
| `expired` | 上游已不可查询 |

建议每隔几秒轮询一次。生成通常需要几十秒到几分钟。

## 计费

`GET` 和 `DELETE` 请求不额外计费。所有任务创建时固定价格规则；具体扣费时间取决于模型。Mini 和标准版 2.0 在任务成功接受时按秒计费，任务失败、取消或过期后由后台退费。Fast 和 2.5 在任务完成后，按上游实际 `completion_tokens` 结算；失败任务不收费。

Mini 按美元/秒计费：

| 分辨率 | 无视频输入 | 有视频输入 |
| - | - | - |
| `480p` | \$0.06 / 输出秒 | \$0.0375 /（输入 + 输出）秒 |
| `720p` | \$0.12 / 输出秒 | \$0.075 /（输入 + 输出）秒 |

4 秒 `480p` 文生视频约为 `$0.24`。当前价格以 [控制台](https://console.pipellm.ai) 为准。

标准版 2.0 保留现有售价 **`$0.48 / 输出秒`**。Fast 为 **`$4.080882 / 百万视频 Token`**；2.5 的 480p / 720p 为 **`$10.294118 / 百万视频 Token`**，1080p 为 **`$11.323529 / 百万视频 Token`**。这两款 Token 价格按 **1 美元 = 6.8 人民币**换算。视频 Token 不等于时长或文本 Token，最终以实际生成用量结算。

## API 参考

<Columns cols={3}>
  <Card title="创建" href="/zh/api-reference/video/create">
    `POST /v2/videos`
  </Card>

  <Card title="查询" href="/zh/api-reference/video/get">
    `GET /v2/videos/{id}`
  </Card>

  <Card title="取消" href="/zh/api-reference/video/cancel">
    `DELETE /v2/videos/{id}`
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.