> ## 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 概览](/cn/api-reference/endpoint/kling)。

## 提交响应

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

保存 `data.id`，使用 [查询 Kling 任务](/cn/api-reference/endpoint/kling-tasks) 轮询至 `succeeded` 或 `failed`。提交成功不代表生成完成。