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

# 视频生成

> 生成具有明确公共操作、异步轮询和特定模型媒体输入的视频。

视频生成是异步的。 `POST /v1/videos/generations` 返回一个公共任务标识符，通常还会返回一个 `poll_url`；最终视频将在后续状态响应中出现。

当所选 Seedance 模型可使用 TokenLab 素材库时，图片 URL 和受支持的内联 data URL 会在生成前自动准备为可复用的 TokenLab 素材。如果准备超过 60 秒，请在返回的 `auto_material_asset_ids` 变为 `ACTIVE` 后重试。如果所选模型暂不可使用素材库，普通图片输入仍走常规图片路径。

## 统一视频 API 与火山兼容入口

跨模型视频生成建议使用 `/v1/videos/generations`。如果你正在迁移已有的 Seedance 2.0 集成，并且请求已经是火山风格的 `content[]` 或 Action 形式，可以使用 `/api/v3` 下的 Seedance 兼容入口。两种入口都使用 TokenLab Bearer API Key 和异步轮询，但请求与响应结构不同。

## 支持的操作

在生产中使用明确的 `operation`。TokenLab 可以从输入中推断某些操作，但明确的操作值使得验证、支持和重试更加清晰。

| 操作                   | 必需或典型输入                                                      | 用例           |
| -------------------- | ------------------------------------------------------------ | ------------ |
| `text-to-video`      | `prompt`                                                     | 仅从文本生成       |
| `image-to-video`     | `image_url` 或兼容的 `image`                                     | 动画化起始图像      |
| `reference-to-video` | `reference_images` 和可选的 `video_urls` / `audio_urls`（在支持的模型上） | 保持身份、风格或资产引用 |
| `start-end-to-video` | `start_image`, `end_image`                                   | 控制第一帧和最后一帧   |
| `video-to-video`     | `video_url` 或特定模型的 `task_id`                                 | 转换或放大现有剪辑    |
| `motion-control`     | `image_url` 加 `video_url`                                    | 将运动参考应用于主题   |
| `audio-to-video`     | `audio_url`                                                  | 音频条件的视频流     |
| `video-extension`    | `task_id`, `extend_at` 或特定模型的扩展字段                            | 继续生成的视频      |

## 模型发现

```bash theme={null}
curl "https://api.tokenlab.sh/v1/models?recommended_for=video" \\
  -H "Authorization: Bearer sk-your-api-key"
```

`model` 应使用 TokenLab 展示的模型 ID，再用 `operation` 和对应媒体输入选择操作能力。示例包括 `wan-2.7`、`happyhorse-1.0`、`viduq3`、`viduq3-mix`、`pixverse-v6`、`kling-3.0-video`、`veo3.1`、`seedance-2.0`；不要把提供商的操作名称当成 TokenLab 模型名。

在依赖于诸如 `reference_images`、`kling_elements`、`output_audio`、`duration`、`resolution` 或 `aspect_ratio` 等特定字段之前，请阅读所选模型的详细信息。

## 创建请求

```bash theme={null}
curl https://api.tokenlab.sh/v1/videos/generations \\
  -H "Authorization: Bearer sk-your-api-key" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "veo3.1",
    "operation": "text-to-video",
    "prompt": "一只猫在阳光明媚的花园中漫步的宁静电影镜头",
    "duration": 4,
    "aspect_ratio": "16:9"
  }'
```

对于生产媒体输入，优先使用公共 `https` URL 而不是内联 `data:` URL。如果使用临时访问 URL，请确保它在 TokenLab 完成任务创建前保持有效。

## 输入和特定模型字段

* Veo 3 系列请求在省略 `output_audio` 时默认启用音频。当模型支持切换且您的用户体验依赖于声音时，请明确设置它。
* `kling_elements` 用于 `kling-3.0-video` 图像条件请求。在 `prompt` 中将每个元素引用为 `@name`；不要将其与 `output_audio=true` 结合使用。
* 使用 Seedance 2.0 家族的 4K 输出、Fast/Mini 分辨率边界或多模态参考输入前，请阅读 [Seedance 2.0 视频模型指南](/zh/guides/seedance-2-video)。
* 对于 `grok-imagine-video`，video-to-video 使用公共 `.mp4` `video_url`；特定模型的限制如 `duration` 和 `resolution` 必须来自模型说明。

## PixVerse 与 HappyHorse

| 模型                           | 操作                                                                            | 输入                                                                          | 分辨率                     | 时长                            | 音频参数                        |
| ---------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ----------------------- | ----------------------------- | --------------------------- |
| `pixverse-c1`, `pixverse-v6` | `text-to-video`, `image-to-video`, `start-end-to-video`, `reference-to-video` | `prompt`; `image_url`; `start_image` + `end_image`; `reference_images`      | 360p, 540p, 720p, 1080p | 1 至 15 秒的整数                   | `output_audio`, 默认为 `false` |
| `pixverse-v5.6`              | `text-to-video`, `image-to-video`, `start-end-to-video`, `reference-to-video` | 与 C1、V6 相同                                                                  | 360p, 540p, 720p, 1080p | 5、8 或 10 秒；1080p 支持 5 或 8 秒   | `output_audio`, 默认为 `false` |
| `happyhorse-1.0`             | `text-to-video`, `image-to-video`, `reference-to-video`, `video-to-video`     | `prompt`; `image_url`; `reference_images`; `video_url` + `reference_images` | 720p, 1080p             | 生成操作为 3 至 15 秒；视频转视频输出最长 15 秒 | 不要传入 `output_audio`         |

在 TokenLab 上，上述 PixVerse 模型不接受 `operation=video-extension`。

```bash theme={null}
curl https://api.tokenlab.sh/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "pixverse-v6",
    "operation": "image-to-video",
    "prompt": "A slow camera move through a neon-lit street",
    "image_url": "https://example.com/start.jpg",
    "resolution": "1080p",
    "duration": 5,
    "output_audio": true
  }'
```

## 轮询结果

首先使用返回的 `poll_url`。如果需要固定端点，请使用 `GET /v1/tasks/{id}`，并使用创建响应中的相同 `id` / `task_id`。

完成的视频任务可能会根据模型和输出数量返回 `video_url`、`video` 或 `videos`。将 `billing_transaction_id` 视为计费标识符，而不是任务标识符。

## 常见陷阱

* 不要硬编码旧的视频状态路径；优先使用 `poll_url`。
* 除非模型说明允许，否则不要将第一帧字段与专用的参考图像流结合使用。
* 不要假设 `duration` 描述输入参考视频的长度；它通常控制生成输出的长度。
* 在超时后不要重试创建请求，而不检查任务是否已经创建。

## API 参考

| 主题     | 参考                                                 |
| ------ | -------------------------------------------------- |
| 创建视频   | [创建视频](/zh/api-reference/video/create-video)       |
| 获取视频状态 | [获取视频状态](/zh/api-reference/video/get-video-status) |
| 获取任务状态 | [获取任务状态](/zh/api-reference/tasks/get-task-status)  |
| 取消任务   | [取消任务](/zh/api-reference/tasks/cancel-task)        |
| 计费与定价  | [计费与定价](/zh/guides/billing)                        |