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

# Kling Omni 生成與編輯

> Kling 3.0 Omni 與 O1 的圖片參考、影片參考和影片編輯。

使用 MixRoute API Key，以 `Authorization: Bearer $MIXROUTE_API_KEY` 認證，請求體為 JSON。模型 ID 位於 URL 中，不在請求體中重複傳 `model`；不新增 `/v1`，也不使用 `metadata` 包裝。

## 支援模型

| 模型 ID                                                        | 解析度               | 普通生成時長（秒） |
| ------------------------------------------------------------ | ----------------- | --------- |
| [kling-3.0-omni](/zh-hant/model-api/kuaishou/kling-3.0-omni) | 720p / 1080p / 4k | 3-15      |
| [kling-o1](/zh-hant/model-api/kuaishou/kling-o1)             | 720p / 1080p      | 3-10      |

## 素材內容

| 欄位                      | 型別        | 必填  | 說明                                                                                      |
| ----------------------- | --------- | --- | --------------------------------------------------------------------------------------- |
| `contents`              | object\[] | 是   | 文本及多模態輸入集合。可僅包含 prompt 進行文本生成。                                                          |
| `contents[].type`       | string    | 是   | 每項必填：prompt、first\_frame、last\_frame、refer\_image、feature\_video、base\_video 或 element。 |
| `contents[].text`       | string    | 按型別 | prompt 項必填。3.0 Omni 最多 3072 字元（建議 2500）；O1 最多 2500。使用 @image\_1、@video\_1 等引用對應 id。     |
| `contents[].url`        | string    | 按型別 | 影像/影片項必填。圖片支援 URL 或 Base64；影片使用公網 URL。feature\_video 用於特徵參考，base\_video 用於編輯底片。         |
| `contents[].element_id` | string    | 按型別 | element 項必填，必須是上游路由賬戶可訪問的資產。                                                            |
| `contents[].id`         | string    | 按型別 | element 項必填；影像/影片項可選，需要在提示詞中引用時設定。同任務不能重複。                                              |

## 生成設定

| 欄位                      | 型別      | 必填  | 說明                                                                                                 |
| ----------------------- | ------- | --- | -------------------------------------------------------------------------------------------------- |
| `settings.resolution`   | string  | 否   | 預設 720p。3.0 Omni：720p/1080p/4k；O1：720p/1080p。                                                      |
| `settings.duration`     | integer | 否   | 預設 5。3.0 Omni：3-15；O1：3-10。O1 僅首幀且無 refer\_image/影片參考時只能 5 或 10 秒。                                 |
| `settings.aspect_ratio` | string  | 按場景 | 16:9（預設）、9:16 或 1:1；沒有首幀和影片參考時須明確提供。                                                               |
| `settings.audio`        | string  | 否   | 預設 off。3.0 Omni：native/original/off；O1：original/off。original 保留參考影片原聲；有影片輸入時 3.0 Omni 不能使用 native。 |
| `settings.multi_shot`   | boolean | 否   | 僅 3.0 Omni，預設 true。feature\_video 場景須 true；base\_video 編輯不支援多鏡頭，設 false。O1 不傳。                     |

## 輸入組合

* 兩個型號都最多輸入一個影片；`base_video` 編輯不能搭配首幀或尾幀。
* 首尾幀必須成對或僅首幀，不支援僅尾幀。O1 首尾幀模式不能加參考圖或 Element；O1 的 `feature_video` 可搭配首幀，但不能尾幀。
* O1 僅支援多圖 Element：無影片時，參考圖片與 Element 合計最多 7 個；有影片時最多 4 個。
* 3.0 Omni 無影片且僅使用多圖 Element 時，參考圖片與多圖 Element 合計最多 7 個；加入影片角色 Element 時，影片角色最多 3 個，參考圖片與多圖 Element 合計最多 4 個。
* 3.0 Omni 有影片時，可加最多 4 個參考圖片/多圖 Element，或最多 1 個影片角色 Element；不能同時搭配影片角色與參考圖片/多圖 Element。首幀/首尾幀生成最多 3 個 Element。
* 3.0 Omni 使用 `feature_video` 時只允許 `audio=off`；使用 `base_video` 時選擇 `off` 或 `original`。無影片輸入時才可使用 `native`。

## 媒體限制

| 素材          | 限制                                                                             |
| ----------- | ------------------------------------------------------------------------------ |
| 圖片          | JPG/JPEG/PNG，最多 50 MB；寬高均至少 300 px，寬高比 1:2.5 至 2.5:1。                          |
| 3.0 Omni 影片 | MP4/MOV，最多 200 MB，3-15.5 秒；寬高各 700-4553 px，總畫素不超過 8294400；寬高比 0.4-2，24-60 fps。 |
| O1 影片       | MP4/MOV，最多 200 MB，3-10 秒；寬高各 700-2160 px，24-60 fps。                            |

## 分鏡提示詞

僅 3.0 Omni 支援多鏡頭生成。開啟 `settings.multi_shot` 後，使用 `shot n, m, words;` 格式，以英文分號分隔：1-6 個鏡頭，每鏡至少 1 秒，所有鏡頭時長之和等於 `settings.duration`，每鏡提示詞最多 512 字元。`base_video` 編輯不支援該模式；不要將多鏡頭引數傳給 O1。素材引用名須唯一，避免名稱互相包含或與提示詞中的其他文字重疊。

## 圖片參考示例

先設定環境變數 `MIXROUTE_API_KEY`。將 `example.com` 媒體地址替換為無需登入即可訪問的真實素材。

```bash theme={null}
curl --request POST "https://api.mixroute.ai/kling/omni-video/kling-3.0-omni" \
  --header "Authorization: Bearer $MIXROUTE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "contents": [
    {
      "type": "prompt",
      "text": "The mug in @image_1 slowly rotates on a white tabletop. Soft studio lighting."
    },
    {
      "type": "refer_image",
      "url": "https://example.com/reference.png",
      "id": "image_1"
    }
  ],
  "settings": {
    "resolution": "720p",
    "duration": 5,
    "aspect_ratio": "16:9",
    "audio": "native",
    "multi_shot": false
  }
}'
```

## O1 影片編輯示例

```bash theme={null}
curl --request POST "https://api.mixroute.ai/kling/omni-video/kling-o1" \
  --header "Authorization: Bearer $MIXROUTE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "contents": [
    {
      "type": "prompt",
      "text": "Change the red mug in @video_1 to blue. Preserve the original motion and background."
    },
    {
      "type": "base_video",
      "url": "https://example.com/source.mp4",
      "id": "video_1"
    }
  ],
  "settings": {
    "resolution": "720p",
    "duration": 5,
    "audio": "off"
  }
}'
```

通用選項見 [Kling 概覽](/zh-hant/api-reference/endpoint/kling)。

## 提交響應

```json theme={null}
{
  "code": 0,
  "message": "",
  "request_id": "REQUEST_ID",
  "data": {
    "id": "task_example",
    "status": "submitted"
  }
}
```

儲存 `data.id`，使用 [查詢 Kling 任務](/zh-hant/api-reference/endpoint/kling-tasks) 輪詢至 `succeeded` 或 `failed`。提交成功不代表生成完成。