> ## 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 動作控制

> 使用人物圖片和動作參考影片生成 Kling 影片。

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

支援 `kling-3.0` 與 `kling-2.6`。兩者均只支援 `720p` / `1080p`，不支援 `4k`。這是基於人物動作參考的控制，不是獨立的 motion 型號或單純攝像機運鏡引數。

## 請求引數

| 欄位                               | 型別        | 必填  | 說明                                                                            |
| -------------------------------- | --------- | --- | ----------------------------------------------------------------------------- |
| `contents`                       | object\[] | 是   | 輸入集合，提供外觀圖片與動作影片，可附提示詞。                                                       |
| `contents[].type`                | string    | 是   | 每項必填：prompt、image、video；3.0 另支援 element。                                      |
| `contents[].text`                | string    | 按型別 | prompt 項必填，最多 2500 字元，可描述正向與負向要求。                                             |
| `contents[].url`                 | string    | 按型別 | image/video 項必填。圖片可用 URL 或 Base64，影片用公網 URL。                                  |
| `contents[].element_id`          | string    | 按型別 | 僅 3.0 的 element 項，必填，最多 1 個 Element。                                          |
| `contents[].id`                  | string    | 按型別 | element 項必填，同任務唯一，供提示詞 @id 引用。                                                |
| `settings.character_orientation` | string    | 是   | video：人物朝向跟隨影片，參考影片 3-30 秒；image：跟隨圖片，參考影片 3-10 秒。使用 Element 時朝向跟隨影片，設 video。 |
| `settings.resolution`            | string    | 否   | 720p（預設）或 1080p，不支援 4k。                                                       |
| `settings.audio`                 | string    | 否   | original（預設）保留參考影片原聲；off 靜音。沒有 native。                                        |

<Warning>
  不要傳 `settings.duration`。輸出時長由可用的連續動作決定，可能短於參考影片；至少需要提取出 3 秒有效動作。按實際生成時長結算。
</Warning>

## 媒體限制

* 圖片：JPG/JPEG/PNG，最多 50 MB；寬高至少 300 px，寬高比 1:2.5 至 2.5:1。
* 影片：MP4/MOV，最多 100 MB，寬高各 340-3850 px；時長按 `character_orientation` 選擇。
* 圖片與影片中的人物比例應接近，頭部、肢體清晰可見，避免遮擋。動作影片優先單人、單鏡頭、連續運動，避免剪輯與快速動作。

## 請求示例

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

```bash theme={null}
curl --request POST "https://api.mixroute.ai/kling/motion-control/kling-3.0" \
  --header "Authorization: Bearer $MIXROUTE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "contents": [
    {
      "type": "prompt",
      "text": "The person follows the reference motion."
    },
    {
      "type": "image",
      "url": "https://example.com/person.png"
    },
    {
      "type": "video",
      "url": "https://example.com/motion.mp4"
    }
  ],
  "settings": {
    "resolution": "720p",
    "character_orientation": "video",
    "audio": "original"
  }
}'
```

通用選項見 [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`。提交成功不代表生成完成。