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

# Kling v4 影片生成

> 以同一個 kling-4.0 模型支援文字生成影片, 參考素材與首/中/尾關鍵影格

三種輸入模式統一使用 `kling-4.0`, 依實際素材自動選擇生成方式. 此為非同步任務介面, 提交後使用平台傳回的任務 ID 查詢結果.

> [!NOTE]
>
> 使用平台 API Key. 中國大陸使用者可將 `https://toapis.com` 換成 `https://toapis.cn`. 可用性依部署後的渠道設定與帳戶權限而定.

## 輸入模式

| 模式 | 請求內容 |
| - | - |
| 文字生成影片 | 僅傳送提示詞與生成規格, 不傳素材. |
| 參考素材 | 使用 `image_urls` / `video_urls` 或 reference 角色素材. 圖片與影片可以組合. |
| 關鍵影格 | 在 `image_with_roles` 明確指定 `first_frame`, `keyframe`, `last_frame`. 不可同時傳參考圖片或影片. |

## 請求參數

**Authorization** `string` *required*

使用 `Bearer YOUR_API_KEY` 驗證.

**model** `string` *required*

固定為 `kling-4.0`. 三種模式不需切換模型 ID.

**prompt** `string` *required*

必填且不可為空白, 最多 8000 個 Unicode 字元. 描述主體, 動作, 鏡頭與素材關係.

**duration** `integer` (default: 5)

整數, 3-30 秒, 預設 5 秒.

**resolution** `string` (default: 720p)

支援 `720p` / `1080p`, 預設 `720p`. 使用本欄位選擇解析度.

**aspect\_ratio** `string`

支援 `auto`, `16:9`, `9:16`, `1:1`, `21:9`. 省略時保留上游預設值; 自動比例可明確傳 `auto`.

**image\_urls** `string[]`

參考圖片 URL 陣列, 最多 10 張. 不依位置推斷首尾影格. 與 reference 圖片角色合計數量, 同一素材建議只用一種寫法.

**video\_urls** `string[]`

參考影片 URL 陣列, 與 `video_with_roles` 合計最多 5 個.

**image\_with\_roles** `object[]`

物件欄位為 `url` 與 `role`. `reference` / `reference_image` 為參考圖; `first_frame`, `keyframe`, `last_frame` 分別為首, 中, 尾影格.

**video\_with\_roles** `object[]`

物件欄位為 `url` 與 `role`. 支援 `reference` / `reference_video`.

**metadata** `object`

布林值 `keep_original_sound` 控制保留參考影片原聲, 如 `{"keep_original_sound": true}`. 僅用於參考影片. 關鍵影格模式不可帶此鍵, 即使為 false.

**client\_business\_id** `string`

選填的客戶業務 ID, 隨任務儲存, 可透過相同介面查詢.

## 素材規則與錯誤邊界

* 使用公開可存取的 HTTP(S) URL, 不可包含使用者名稱或密碼. 本機檔案先透過[上傳圖片](https://docs.toapis.com/docs/zh-Hant/api-reference/uploads/images.md)或[上傳影片](https://docs.toapis.com/docs/zh-Hant/api-reference/uploads/videos.md)取得 URL. 不直接傳本機路徑或 base64.
* 參考模式最多 10 張圖片與 5 個影片. 一般陣列與明確 reference 角色合併計算, 不重複提交相同素材.
* 關鍵影格至少 1 張. 首尾各最多 1 張, 中間最多 8 張, 總數不超過 `min(duration + 1, 10)`. 3 秒最多 4 張, 5 秒最多 6 張, 9-30 秒最多 10 張.
* 中間影格依陣列中 `keyframe` 項目順序排列. 首尾依角色判定, 不依一般圖片位置推斷. 僅首, 僅尾或僅中間影格亦會進入關鍵影格模式.
* 關鍵影格與參考素材互斥. 不使用舊 Kling 的 `mode`, `audio`, `video_list` 或 Omni 引用結構. 不支援 `audio_with_roles`, `metadata.elements`, `metadata.voices`.
* 非法規格, 角色, URL, 數量或模式組合會被拒絕. 修正錯誤後再提交. 本頁未承諾檔案大小, 編碼或輸入影片時長上限, 仍須符合上傳服務及上游要求.

## 請求範例

### 文字生成影片

```json theme={null}
{
  "model": "kling-4.0",
  "prompt": "海浪拍打海岸, 鏡頭緩慢推進, 日落光線",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9"
}
```

### 參考素材

```json theme={null}
{
  "model": "kling-4.0",
  "prompt": "保持參考圖片的人物外觀, 參考影片中的鏡頭運動",
  "duration": 10,
  "resolution": "1080p",
  "aspect_ratio": "16:9",
  "image_urls": [
    "https://example.com/character.png"
  ],
  "video_urls": [
    "https://example.com/motion.mp4"
  ],
  "metadata": {
    "keep_original_sound": true
  }
}
```

### 關鍵影格

```json theme={null}
{
  "model": "kling-4.0",
  "prompt": "從首影格經過中間場景平滑過渡至尾影格",
  "duration": 5,
  "resolution": "1080p",
  "aspect_ratio": "16:9",
  "image_with_roles": [
    {
      "url": "https://example.com/first.png",
      "role": "first_frame"
    },
    {
      "url": "https://example.com/middle-1.png",
      "role": "keyframe"
    },
    {
      "url": "https://example.com/middle-2.png",
      "role": "keyframe"
    },
    {
      "url": "https://example.com/last.png",
      "role": "last_frame"
    }
  ]
}
```

### 提交任務

```bash cURL theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-4.0",
  "prompt": "海浪拍打海岸, 鏡頭緩慢推進, 日落光線",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9"
}'
```

```json theme={null}
{
  "id": "task_example",
  "object": "generation.task",
  "model": "kling-4.0",
  "status": "queued",
  "created_at": 1792713600
}
```

## 查詢任務與計費

回應 `id` 為平台任務 ID, 使用下方介面查詢, 不使用供應商 task\_id. 狀態包括 `queued`, `in_progress`, `completed`, `failed`. 詳見[影片任務狀態](https://docs.toapis.com/docs/zh-Hant/api-reference/tasks/video-status.md)及[任務 Webhook](https://docs.toapis.com/docs/zh-Hant/api-reference/webhooks/task-webhooks.md).

```bash theme={null}
curl --request GET \
  --url https://toapis.com/v1/videos/generations/YOUR_TASK_ID \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

預設為 5 秒 / 720p, 可明確傳入以控制規格. 本頁不提供固定價格, 亦不將原聲開關等同舊版 Sound 計費; 實際費用依帳戶報價及任務 usage / billing 為準.


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