> ## 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.

# 建立影片

> 建立一個影片生成任務

## 概覽

影片生成是非同步的。你提交請求後，會收到一個任務 ID 與 `poll_url`，之後再透過輪詢取得結果。

### 輪詢行為

建立回應會返回規範非同步識別 `id`，並通常同時回傳 `task_id`。請優先輪詢 `poll_url`；如果需要固定狀態入口，請使用 `GET /v1/tasks/{id}`。

如果建立回應返回 `poll_url`，請直接使用該 URL。若它指向 `/v1/tasks/{id}`，請將其視為規範的固定狀態查詢入口。

為了獲得最可靠的輪詢行為，請嚴格使用建立請求回傳的 `poll_url`。

### 模型與媒體行為

音訊輸出是否開啟取決於具體模型。在 TokenLab 中，Veo 3 與 Seedance 請求在省略 `output_audio` 時預設按開啟音訊處理。模型支援音訊控制時，可用 `output_audio` 明確切換；相容別名 `outputAudio` 和 `generate_audio` 也可使用，但多個欄位同時出現時值必須一致。

在生產環境中，建議優先使用可從公網直接存取的 `https` URL 作為圖片、影片與音訊輸入。相容模型仍支援內嵌 `data:` URL，但大體積 base64 在重試、觀測與除錯時通常較不友善。

## 請求主體

<ParamField body="model" type="string" default="veo3.1">
  影片模型 ID。請使用 `veo3.1`、`wan-2.7`、`happyhorse-1.0`、`viduq3`、`pixverse-v6`、`kling-3.0-video` 等模型 ID；文生影片、圖生影片、參考圖生影片等能力用 `operation` 選擇。目前公開影片能力請參考[影片生成指南](/zh-Hant/guides/video-generation)和 [Models API](/zh-Hant/api-reference/models/list-models)。
</ParamField>

<Note>
  **PixVerse**

  * 模型: `pixverse-c1`, `pixverse-v6`, `pixverse-v5.6`
  * 操作: `text-to-video`, `image-to-video`, `start-end-to-video`, `reference-to-video`
  * 音訊選擇器: `output_audio`, 預設為 `false`

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

  **HappyHorse**

  * 模型: `happyhorse-1.0`
  * 操作: `text-to-video`, `image-to-video`, `reference-to-video`, `video-to-video`
  * 音訊選擇器: 請勿傳送 `output_audio`
</Note>

<ParamField body="prompt" type="string" required>
  要生成影片的文字描述。大多數公開影片模型都需要這個欄位。
</ParamField>

<ParamField body="operation" type="string">
  要執行的影片操作。支援 `text-to-video`、`image-to-video`、`reference-to-video`、`start-end-to-video`、`video-to-video`、`video-extension`、`audio-to-video` 與 `motion-control`。TokenLab 可以根據輸入自動推斷操作，但在生產環境中仍建議明確傳入 `operation`。
</ParamField>

<ParamField body="image_url" type="string">
  用於圖生影片的起始圖片 URL。為了獲得最廣泛的跨模型相容性，建議優先使用 `image_url`。
</ParamField>

<ParamField body="image" type="string">
  以內嵌 data URL 形式提供的圖片（例如 `data:image/jpeg;base64,...`）。相容模型支援這種方式，但 `image_url` 的相容性更廣。
</ParamField>

<ParamField body="reference_images" type="array">
  用於參考圖生影片的參考圖輸入。可傳數量取決於模型。對於 `seedance-2.0` 與 `seedance-2.0-fast`，TokenLab 目前支援最多 9 張參考圖，外加最多 3 段參考影片與 3 段參考音訊。模型選型、4K 邊界和 Mini 說明請參考 [Seedance 2.0 影片模型指南](/zh-Hant/guides/seedance-2-video)。建議優先使用公開 `https` URL；相容模型也支援內嵌 `data:` URL。 對於 `grok-imagine-video`，reference-to-video 最多接受 7 個圖片參考，且 `duration` 最高為 10 秒。`grok-imagine-video-1.5-preview` 僅支援圖生影片，不接受參考圖片。
</ParamField>

<ParamField body="material_asset_id" type="string">
  [建立素材](/zh-Hant/api-reference/video/create-material-asset)或自動圖片準備流程回傳的 TokenLab Seedance 素材 ID。素材變為 `ACTIVE` 後，可在能夠使用 TokenLab 素材庫的 Seedance 模型中使用。
</ParamField>

<ParamField body="material_asset_ids" type="array">
  多個 TokenLab Seedance 素材 ID。它們與 `reference_images` 共用 Seedance 圖片參考數量限制；所選模型必須能夠使用 TokenLab 素材庫。
</ParamField>

<Info>
  當所選 Seedance 模型可使用 TokenLab 素材庫時，TokenLab 會在生成前將圖片欄位（`image`、`image_url`、`image_urls`、`reference_images`、`start_image`、`end_image`）準備為可重複使用素材。如果 60 秒內仍未準備完成，API 會回傳 `409 seedance_material_preparing` 和 `auto_material_asset_ids`；請在這些素材變為 `ACTIVE` 後重試。如果所選模型暫不可使用素材庫，一般圖片輸入仍走常規圖片路徑；明確傳入素材 ID 會安全失敗，並回傳可重試的素材可用性錯誤。
</Info>

<ParamField body="reference_image_type" type="string">
  可選的參考圖片角色欄位，用於區分支援 `asset` 與 `style` 兩種參考圖類型的模型。
</ParamField>

<ParamField body="kling_elements" type="array">
  `kling-3.0-video` 的元素引用定義，僅支援帶圖片條件的請求。可定義 1-3 個元素；每個元素包含 `name`、可選 `description`，以及 2-4 個圖片 URL 的 `element_input_urls`。在 `prompt` 中用 `@name` 引用元素。不要將 `kling_elements` 與 `output_audio=true` 組合使用；使用元素引用時請省略 `output_audio` 或設為 `false`。
</ParamField>

<ParamField body="video_url" type="string">
  來源影片的公開 URL。基於影片 URL 的 `video-to-video` 流程與 `motion-control` 需要此欄位；部分衍生流程改用 `task_id`。
</ParamField>

<ParamField body="video_urls" type="array">
  用於支援多模態參考條件控制的額外參考影片輸入。可傳數量取決於模型。對於 `seedance-2.0` 與 `seedance-2.0-fast`，TokenLab 目前支援最多 3 段參考影片。
</ParamField>

<ParamField body="audio_url" type="string">
  提供給 `audio-to-video` 模型使用的公網音訊 URL。
</ParamField>

<ParamField body="audio_urls" type="array">
  用於支援多模態參考條件控制的額外參考音訊輸入。可傳數量取決於模型。對於 `seedance-2.0` 與 `seedance-2.0-fast`，TokenLab 目前支援最多 3 段參考音訊。
</ParamField>

<ParamField body="task_id" type="string">
  某些續寫、延展或衍生流程使用的任務標識符。
</ParamField>

<ParamField body="extend_at" type="integer">
  某些 `video-extension` 流程使用的模型側延展起點參數。
</ParamField>

<ParamField body="extend_times" type="string">
  某些 `video-extension` 流程使用的模型側延展次數或倍率參數。
</ParamField>

<ParamField body="duration" type="integer">
  生成輸出影片的時長（秒）。Seedance 1.5/2.0 模型省略時預設 `5` 秒；傳 `-1` 表示讓模型在支援範圍內自動選擇時長，任務完成前會按保守方式預估費用。
</ParamField>

<ParamField body="seconds" type="integer">
  `duration` 的相容別名。若同時傳 `seconds` 和 `duration`，兩者必須完全一致。對 Seedance，`seconds=-1` 與 `duration=-1` 一樣表示自動時長。
</ParamField>

<ParamField body="aspect_ratio" type="string">
  規範寬高比，例如 `adaptive`、`16:9`、`9:16`、`1:1`、`4:3`、`3:4` 或 `21:9`。Seedance 省略時預設 `adaptive`。
</ParamField>

<ParamField body="resolution" type="string">
  模型相關的輸出解析度。Seedance 省略時預設 `720p`；`seedance-2.0` 支援 `480p`、`720p`、`1080p` 和 `4k`，`seedance-2.0-fast` / `seedance-2.0-mini` 僅支援 `480p` 和 `720p`。
</ParamField>

<ParamField body="output_audio" type="boolean">
  規範的音訊輸出開關。Veo 3 和 Seedance 省略時預設 `true`。`kling-3.0-video` 僅在非元素引用請求中接受該欄位，省略時預設無聲。不要將 `output_audio=true` 與 `kling_elements` 組合使用。
</ParamField>

<ParamField body="draft" type="boolean">
  Seedance 1.5 Pro 草稿工作流開關。僅在支援草稿任務的 Seedance 模型上使用 `draft=true`；不要和 `draft_task_id` 同時傳。
</ParamField>

<ParamField body="draft_task_id" type="string">
  Seedance 1.5 Pro 草稿晉升任務 ID。傳入上一次草稿任務 ID 後建立正式影片；這不是通用影片欄位。
</ParamField>

<ParamField body="ratio" type="string">
  `aspect_ratio` 的相容別名。若同時傳 `ratio` 和 `aspect_ratio`，兩者必須完全一致。
</ParamField>

<ParamField body="generate_audio" type="boolean">
  `output_audio` 的相容別名。`generate_audio`、`output_audio`、`outputAudio` 同時出現時，所有值必須一致。
</ParamField>

<ParamField body="execution_expires_after" type="integer">
  相容影片模型的執行過期時間（秒）。Seedance 省略時預設 `172800` 秒。
</ParamField>

<ParamField body="priority" type="integer">
  相容影片模型的任務優先級，範圍 `0` 到 `9`。不要把 `priority` 與 `service_tier=flex` 組合使用。
</ParamField>

<ParamField body="safety_identifier" type="string">
  相容影片模型的終端使用者安全標識。Seedance 未傳該欄位時，TokenLab 會使用 `user` 的值。
</ParamField>

<ParamField body="service_tier" type="string">
  `default` 對 Seedance 2.0 會按相容 no-op 處理。只有所選模型明確支援時才可使用 `flex`。
</ParamField>

<ParamField body="frames" type="integer">
  相容影片模型的可選幀數。Seedance 2.0 模型和 Seedance 1.5 Pro 不支援該欄位。
</ParamField>

<ParamField body="camera_fixed" type="boolean">
  相容影片模型的固定相機開關。Seedance 2.0 模型不支援該欄位。
</ParamField>

<ParamField body="fps" type="integer">
  每秒影格數（1-120），僅在模型公開支援 FPS 控制時生效。
</ParamField>

<ParamField body="negative_prompt" type="string">
  希望在影片生成過程中避免出現的內容。
</ParamField>

<ParamField body="seed" type="integer">
  用於可重現生成的隨機種子。Seedance 省略時使用 `-1` 表示隨機種子。
</ParamField>

<ParamField body="cfg_scale" type="number">
  提示詞遵循強度（0-20），僅在公開模型支援此控制項時生效。
</ParamField>

<ParamField body="motion_strength" type="number">
  動作強度（0-1），僅在公開模型支援這個欄位時生效。
</ParamField>

<ParamField body="start_image" type="string">
  `start-end-to-video` 中使用的起始幀圖片 URL 或相容圖片輸入。
</ParamField>

<ParamField body="end_image" type="string">
  `start-end-to-video` 中使用的結束幀圖片 URL 或相容圖片輸入。
</ParamField>

<ParamField body="size" type="string">
  相容影片模型使用的模型相關尺寸檔位參數。
</ParamField>

<ParamField body="watermark" type="boolean">
  某些模型暴露的浮水印開關。Seedance 省略時預設 `false`。
</ParamField>

<ParamField body="effect_type" type="string">
  某些特效或編輯流程所使用的模型側效果選擇器。
</ParamField>

<ParamField body="user" type="string">
  終端使用者的唯一標識。對 Seedance，如果未傳 `safety_identifier`，TokenLab 會使用該值。
</ParamField>

## 相容說明

* 規範公開欄位繼續使用 snake\_case：`aspect_ratio`、`output_audio`、`reference_images` 和 `reference_image_type`。
* 為了相容既有呼叫，TokenLab 也接受 `ratio`、`generate_audio`、`outputAudio`、`seconds`、`referenceImages` 和 `referenceImageType`。
* 如果規範欄位和別名欄位同時出現，值必須一致；衝突會在建立任務前被拒絕。
* 如果省略 `operation`，TokenLab 會根據輸入自動推斷操作；生產環境仍建議明確傳入。

## 輸入最佳實踐

* 對於 `image_url`、`reference_images`、`video_url` 與 `audio_url`，建議優先使用公網可存取的 `https` URL。
* 盡量避免在同一個請求中混用內嵌 base64 與遠端 URL；統一採用同一種表示方式更容易排錯與重試。
* 請確保遠端媒體 URL 的有效期足以覆蓋重試窗口與非同步任務建立流程。

## Seedance 參數

對於 Seedance 1.5/2.0 模型，統一介面以 TokenLab 欄位為主，同時接受官方常見別名 `ratio` 和 `generate_audio`。省略 Seedance 參數時會使用這些預設值：`duration=5`、`resolution=720p`、`aspect_ratio=adaptive`、`output_audio=true`、`watermark=false`、`return_last_frame=false`、`execution_expires_after=172800`、`priority=0`、`seed=-1`。

`duration=-1` 或 `seconds=-1` 表示讓 Seedance 在模型支援範圍內自動選擇輸出時長。TokenLab 會在任務完成前按保守方式預估費用，並在可取得完成任務 usage 時按實際結果結算。`service_tier=default` 對 Seedance 2.0 作為相容 no-op 接受；`service_tier=flex`、`frames`、`camera_fixed` 會在所選模型不支援時被拒絕。

### Seedance 範例

```bash cURL theme={null}
curl -X POST "https://api.tokenlab.sh/v1/videos/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "prompt": "A sleek product reveal with cinematic camera movement",
    "operation": "text-to-video",
    "duration": -1,
    "aspect_ratio": "adaptive",
    "resolution": "720p",
    "output_audio": true
  }'
```

## 回應

<ResponseField name="id" type="string">
  規範非同步任務 ID。
</ResponseField>

<ResponseField name="task_id" type="string">
  用於輪詢的唯一任務識別碼。
</ResponseField>

<ResponseField name="poll_url" type="string">
  此任務建議使用的輪詢 URL。查詢狀態時請使用這個精確路徑。
</ResponseField>

<ResponseField name="billing_transaction_id" type="string">
  當結算已完成時返回 TokenLab 帳單交易 ID。它對應 dashboard / 對帳使用的交易識別，與非同步 `id` / `task_id` 不同。
</ResponseField>

<ResponseField name="status" type="string">
  初始狀態：`pending`。
</ResponseField>

<ResponseField name="created" type="integer">
  建立任務時的 Unix 時間戳。
</ResponseField>

<ResponseField name="model" type="string">
  所使用的模型。
</ResponseField>

<ResponseField name="video_url" type="string">
  結果已就緒時可直接使用的影片 URL。
</ResponseField>

<ResponseField name="video" type="object">
  可用時返回單一影片物件，包含 `url`、`duration`、`width` 與 `height`。
</ResponseField>

<ResponseField name="videos" type="array">
  當任務生成多個輸出時，可能出現影片陣列。
</ResponseField>

<ResponseField name="error" type="string">
  任務失敗時返回的錯誤訊息或結構化錯誤物件。
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.tokenlab.sh/v1/videos/generations" \
    -H "Authorization: Bearer sk-your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "veo3.1",
      "prompt": "A cat walking through a garden, cinematic lighting",
      "operation": "text-to-video",
      "duration": 4,
      "aspect_ratio": "16:9"
    }'
  ```

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

  response = requests.post(
      "https://api.tokenlab.sh/v1/videos/generations",
      headers={
          "Authorization": "Bearer sk-your-api-key",
          "Content-Type": "application/json"
      },
      json={
          "model": "veo3.1",
          "prompt": "A cat walking through a garden, cinematic lighting",
          "operation": "text-to-video",
          "duration": 4,
          "aspect_ratio": "16:9"
      }
  )

  data = response.json()
  task_id = data["task_id"]
  print(f"Poll URL: {data['poll_url']}")
  print(f"Task ID: {task_id}")
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "status": "pending",
    "model": "veo3.1",
    "created": 1706000000
  }
  ```
</ResponseExample>

## 圖生影片

```python theme={null}
response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "hailuo-2.3-standard",
        "prompt": "The scene begins from the provided image and adds gentle natural motion.",
        "operation": "image-to-video",
        "image_url": "https://example.com/image.jpg",
        "duration": 6,
        "aspect_ratio": "16:9"
    }
)
```

## Kling 3.0 元素引用

需要元素引用時，請在 `kling-3.0-video` 請求中傳入 `kling_elements`。請求需要包含圖片條件輸入（`image_url`、`image_urls`、`start_image` 或 `end_image`），並在提示詞中用 `@name` 引用對應元素。

```python theme={null}
response = requests.post("https://api.tokenlab.sh/v1/videos/generations",
    headers=headers,
    json={
        "model": "kling-3.0-video",
        "prompt": "Place @hero_bag on a studio turntable with soft product lighting.",
        "operation": "image-to-video",
        "image_url": "https://example.com/studio-start.png",
        "duration": 5,
        "resolution": "720p",
        "kling_elements": [
            {
                "name": "hero_bag",
                "description": "black leather handbag",
                "element_input_urls": [
                    "https://example.com/bag-front.png",
                    "https://example.com/bag-side.png"
                ]
            }
        ]
    }
)
```

## 參考圖生影片

當模型支援專門的參考條件控制時，請使用 `operation=reference-to-video`。在 TokenLab 請求中，圖片參考素材使用 `reference_images`，多模態參考影片與參考音訊則分別使用 `video_urls` 與 `audio_urls`。對於 `seedance-2.0` 與 `seedance-2.0-fast`，TokenLab 目前支援最多 9 張參考圖，外加最多 3 段參考影片與 3 段參考音訊。模型選型、4K 邊界和 Mini 說明請參考 [Seedance 2.0 影片模型指南](/zh-Hant/guides/seedance-2-video)。`duration` 只控制生成輸出時長，不單獨限制參考影片輸入時長。 對於 `grok-imagine-video`，reference-to-video 最多接受 7 個圖片參考（`reference_images` 或 `image_urls`），且 `duration` 最高為 10 秒。不要把參考圖片與 `image_url` / `image` 首幀輸入混用。`grok-imagine-video-1.5-preview` 僅支援圖生影片。

```python theme={null}
response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "veo3.1",
        "prompt": "Keep the same subject identity and palette while adding subtle motion.",
        "operation": "reference-to-video",
        "reference_images": [
            "https://example.com/ref-a.jpg",
            "https://example.com/ref-b.jpg"
        ],
        "reference_image_type": "asset",
        "duration": 8,
        "resolution": "720p",
        "aspect_ratio": "9:16"
    }
)
```

## 首尾幀控制

使用 `start_image` 與 `end_image` 控制首幀與尾幀：

```python theme={null}
response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "viduq2-pro",
        "prompt": "Smooth transition from day to night",
        "operation": "start-end-to-video",
        "start_image": "https://example.com/day.jpg",
        "end_image": "https://example.com/night.jpg",
        "duration": 5,
        "resolution": "720p",
        "aspect_ratio": "16:9"
    }
)
```

## 影片轉影片

對於 `grok-imagine-video` 的 video-to-video，請在 `video_url` 中傳入公開 HTTPS `.mp4` URL。TokenLab 會把它轉換為 xAI REST 的 `video.url` 請求體。你可以將 `resolution` 設為 `480p` 或 `720p`；此編輯流程不接受 `duration` 與 `aspect_ratio`。

當模型接受現有影片作為主要輸入時，請使用 `operation=video-to-video`。

```python theme={null}
response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "grok-imagine-video",
        "operation": "video-to-video",
        "video_url": "https://example.com/source.mp4",
        "prompt": "Enhance the clip while preserving the original motion.",
        "resolution": "720p"
    }
)
```

## 動作控制

當模型同時需要主體圖片與動作參考影片時，請使用 `operation=motion-control`。TokenLab 會把公開的 `image_url` + `video_url` 請求形態轉換為相容的動作控制輸入。

```python theme={null}
response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "kling-3.0-motion-control",
        "operation": "motion-control",
        "prompt": "Keep the subject stable while following the motion reference.",
        "image_url": "https://example.com/subject.png",
        "video_url": "https://example.com/motion.mp4",
        "resolution": "720p"
    }
)
```

## 模型探索

公開影片模型庫存與支援操作會持續變化。接入某個模型特定流程前，請以 [Models API](/zh-Hant/api-reference/models/list-models) 確認目前支援情況：

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

curl "https://api.tokenlab.sh/v1/models/veo3.1" \
  -H "Authorization: Bearer sk-your-api-key"
```

依賴模型特定操作或欄位前，請讀取單模型詳情回應。`audio-to-video`、`video-extension` 等操作屬於模型特定能力；請在那裡確認即時可用性，不要依賴本頁的靜態範例。