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

# 视频生成

> 异步视频生成。提交任务后，通过 id 轮询（或提供 callback_url）。

## 端点

```
POST https://vibetoken.cn/v1/videos/generations
GET  https://vibetoken.cn/v1/videos/generations/{id}
```

视频生成是**异步的**。`POST` 会立即返回一个 `id` 以及 `status: "pending"`。可通过轮询 `GET /v1/videos/generations/{id}` 或设置 `callback_url` 来获取结果。

## 请求头

| Header          | Value                       |
| --------------- | --------------------------- |
| `Authorization` | `Bearer sk-rb-xxxxxxxxxxxx` |
| `Content-Type`  | `application/json`          |

## 请求体（POST）

<ParamField body="model" type="string" required>
  视频模型 ID。例如 `bytedance/seedance-2-0`、`kuaishou/kling-2-1`、`minimax/hailuo-pro`、`alibaba/wan-2-7-t2v`。
</ParamField>

<ParamField body="prompt" type="string" required>
  视频的文本描述。
</ParamField>

<ParamField body="duration" type="number">
  时长（秒）。取决于具体模型（常见为 `5`、`8`、`10`）。
</ParamField>

<ParamField body="aspect_ratio" type="string">
  例如 `16:9`、`9:16`、`1:1`。
</ParamField>

<ParamField body="resolution" type="string">
  例如 `720p`、`1080p`。取决于具体模型。
</ParamField>

<ParamField body="image_urls" type="array">
  图生视频模型（`*-i2v`、`*-image-to-video`）必填。每一项可以是公开的 HTTPS URL，**也可以**是内联的 base64 `data:` URI（例如 `data:image/png;base64,…`）——内联图片会被自动解码并托管。对于超过几 MB 的内容，建议通过 `POST /v1/uploads` 上传并传入返回的 URL。
</ParamField>

<ParamField body="callback_url" type="string">
  可选。当任务完成时，VibeToken 会将最终结果 `POST` 到此 HTTPS URL。参见 [异步任务 → 回调](/essentials/async-tasks#option-2-callback-url)。
</ParamField>

## 提交任务

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://vibetoken.cn/v1/videos/generations \
    -H "Authorization: Bearer sk-rb-xxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "bytedance/seedance-2-0",
      "prompt": "A cat playing piano in a sunny living room",
      "duration": 8,
      "aspect_ratio": "16:9"
    }'
  ```

  ```python Python theme={null}
  import requests

  r = requests.post(
      "https://vibetoken.cn/v1/videos/generations",
      headers={"Authorization": "Bearer sk-rb-xxxxxxxxxxxx"},
      json={
          "model": "bytedance/seedance-2-0",
          "prompt": "A cat playing piano in a sunny living room",
          "duration": 8,
          "aspect_ratio": "16:9",
      },
  )
  print(r.json()["id"])
  ```
</CodeGroup>

### 响应（POST）

```json theme={null}
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "object": "video.generation",
  "status": "pending",
  "model": "bytedance/seedance-2-0",
  "created": 1776245700
}
```

## 轮询状态（GET）

```
GET /v1/videos/generations/{id}
```

```python theme={null}
import time, requests

def wait_for_video(gen_id, api_key, interval=3, timeout=600):
    headers = {"Authorization": f"Bearer {api_key}"}
    url = f"https://vibetoken.cn/v1/videos/generations/{gen_id}"
    elapsed = 0
    while elapsed < timeout:
        s = requests.get(url, headers=headers).json()
        if s["status"] == "success":
            return s["data"][0]["url"]
        if s["status"] == "failed":
            raise RuntimeError(f"Generation failed")
        time.sleep(interval)
        elapsed += interval
    raise TimeoutError("Generation timed out")
```

### 响应（GET）

运行中：

```json theme={null}
{
  "id": "f47ac10b-...",
  "object": "video.generation",
  "status": "pending",
  "model": "bytedance/seedance-2-0",
  "created": 1776245700
}
```

完成后：

```json theme={null}
{
  "id": "f47ac10b-...",
  "object": "video.generation",
  "status": "success",
  "model": "bytedance/seedance-2-0",
  "data": [
    { "url": "https://media.vibetoken.cn/media/<user>/<gen>/0.mp4" }
  ],
  "created": 1776245700
}
```

| `status`  | 含义                    |
| --------- | --------------------- |
| `pending` | 任务已排队或正在运行            |
| `success` | 生成完成；`data[].url` 已填充 |
| `failed`  | 生成失败                  |

## 图生视频

对于图生视频（i2v）模型（例如 `kuaishou/kling-v2-1-master-i2v`、`bytedance/bytedance-v1-pro-i2v`），需包含 `image_urls`：

```json theme={null}
{
  "model": "kuaishou/kling-v2-1-master-i2v",
  "prompt": "Camera slowly zooms out",
  "image_urls": ["https://example.com/source.jpg"],
  "duration": 5
}
```