> ## 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` 後重試。如果所選模型暫不可使用素材庫，一般圖片輸入仍會走常規圖片路徑。

## 支援的操作

在生產中使用明確的 `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-Hant/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 秒；video-to-video 輸出上限為 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-Hant/api-reference/video/create-video)       |
| 獲取視頻狀態 | [獲取視頻狀態](/zh-Hant/api-reference/video/get-video-status) |
| 獲取任務狀態 | [獲取任務狀態](/zh-Hant/api-reference/tasks/get-task-status)  |
| 取消任務   | [取消任務](/zh-Hant/api-reference/tasks/cancel-task)        |
| 計費與定價  | [計費與定價](/zh-Hant/guides/billing)                        |

## 統一影片 API 與火山相容入口

跨模型影片生成建議使用 `/v1/videos/generations`。如果你正在遷移既有 Seedance 2.0 整合，且請求已是火山風格 `content[]` 或 Action 形式，可以使用 `/api/v3` 下的 Seedance 相容入口。兩種入口都使用 TokenLab Bearer API Key 和非同步輪詢，但請求與回應結構不同。

## OpenAI 風格和火山相容影片 API

跨模型影片生成請使用 TokenLab 統一的 `/v1/videos/generations`。如果你正在遷移已經使用火山風格 `content[]` 或 Action 請求的 Seedance 2.0 整合，可以使用 `/api/v3` 下的 Seedance 相容入口。兩種入口都使用 TokenLab Bearer API Key 和異步輪詢，但請求與回應結構不同。