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

# kling-v3 & kling-v3-omni

> Kling 3.0 与 Kling 3.0 Omni 的可灵旧版 API。

<Tabs>
  <Tab title="文生视频">
    ## 创建任务

    `POST /kling/v1/videos/text2video`

    使用 `model_name: "kling-3.0"` 根据文本提示词生成视频。支持多镜头分镜、运镜、音效与音色引用。

    <div className="kling-api-example-panel">
      ```bash cURL theme={null}
      curl --request POST \
        --url https://www.anyfast.ai/kling/v1/videos/text2video \
        --header 'Authorization: Bearer YOUR_API_KEY' \
        --header 'Content-Type: application/json' \
        --data '{
          "model_name": "kling-3.0",
          "prompt": "一只戴眼镜的兔子坐在桌前阅读报纸",
          "duration": "5",
          "mode": "pro",
          "sound": "on",
          "aspect_ratio": "1:1"
        }'
      ```

      ```json 200 theme={null}
      {
        "id": "860260753860210752",
        "task_id": "860260753860210752",
        "object": "video",
        "model": "kling-v3",
        "status": "",
        "progress": 0,
        "created_at": 1773130665
      }
      ```
    </div>

    ## 请求头

    <ParamField header="Authorization" type="string" required>
      Bearer 身份验证，格式为 `Bearer YOUR_API_KEY`。
    </ParamField>

    <ParamField header="Content-Type" type="string" default="application/json" required>
      请求数据格式，固定为 `application/json`。
    </ParamField>

    ## 请求参数

    <ParamField body="model_name" type="string" required>
      模型名称。Kling 3.0 文生视频固定为 `kling-3.0`。
    </ParamField>

    <ParamField body="prompt" type="string">
      正向提示词，最长 2500 字符。单镜头，或 `shot_type` 为 `intelligence` 时必填。
    </ParamField>

    <ParamField body="negative_prompt" type="string">
      不希望出现在视频中的内容，最长 2500 字符。
    </ParamField>

    <ParamField body="multi_shot" type="boolean" default={false}>
      是否生成多镜头视频。
    </ParamField>

    <ParamField body="shot_type" type="string">
      `multi_shot` 为 `true` 时必填。可选 `customize` 或 `intelligence`。
    </ParamField>

    <ParamField body="multi_prompt" type="object[]">
      自定义分镜列表，支持 1–6 个分镜。每项包含 `index`、`prompt` 和 `duration`。
    </ParamField>

    <ParamField body="voice_list" type="object[]">
      音色引用列表，最多 2 个，每项包含 `voice_id`。
    </ParamField>

    <ParamField body="sound" type="string" default="off">
      是否生成同步音效，可选 `on` 或 `off`。引用音色时必须设为 `on`。
    </ParamField>

    <ParamField body="mode" type="string" default="std">
      输出模式：`std` 为 720p，`pro` 为 1080p，`4k` 为 4K。
    </ParamField>

    <ParamField body="duration" type="string" default="5">
      视频时长，可选 3–15 秒。
    </ParamField>

    <ParamField body="aspect_ratio" type="string" default="16:9">
      画面比例，可选 `16:9`、`9:16` 或 `1:1`。
    </ParamField>

    <ParamField body="cfg_scale" type="number" default={0.5}>
      提示词相关性，范围 0–1。
    </ParamField>

    <ParamField body="camera_control" type="object">
      预设或自定义运镜配置。
    </ParamField>

    <ParamField body="watermark_info" type="object">
      平台水印配置，通过 `enabled` 控制是否添加水印。
    </ParamField>

    ### 多镜头与音色

    * `multi_shot: true` 时必须设置 `shot_type`。`customize` 使用 `multi_prompt`，`intelligence` 根据 `prompt` 自动生成分镜。
    * `multi_prompt` 支持 1–6 个分镜；每项包含 `index`、`prompt` 和 `duration`，单项提示词最长 512 字符，每个分镜至少 1 秒。
    * `voice_list` 最多 2 个音色。按列表顺序在提示词中写入 `<<<voice_1>>>`、`<<<voice_2>>>`，并设置 `sound: "on"`。
    * `voice_id` 来自自定义音色或预置音色接口，不要使用 Lip-Sync 接口返回的音色 ID。

    ```json theme={null}
    {
      "multi_shot": true,
      "shot_type": "customize",
      "multi_prompt": [
        {"index": 1, "prompt": "兔子抬头看向窗外", "duration": "2"},
        {"index": 2, "prompt": "兔子走到窗边", "duration": "3"}
      ],
      "duration": "5"
    }
    ```

    ### 运镜控制

    `camera_control.type` 支持 `simple`、`down_back`、`forward_up`、`right_turn_forward` 和 `left_turn_forward`。使用 `simple` 时，`config` 的以下六项范围均为 -10 到 10，且只能设置一个非 0 值：

    | 字段           | 负值    | 正值    |
    | ------------ | ----- | ----- |
    | `horizontal` | 向左平移  | 向右平移  |
    | `vertical`   | 向下平移  | 向上平移  |
    | `pan`        | 向左摇摄  | 向右摇摄  |
    | `tilt`       | 向下俯仰  | 向上俯仰  |
    | `roll`       | 逆时针滚转 | 顺时针滚转 |
    | `zoom`       | 拉远    | 拉近    |

    <Card title="交互式请求参数" icon="code" href="/zh/api-reference/model-api/kuaishou/kling-v3-t2v">
      在交互式 API 页面中填写并调试完整请求体。
    </Card>

    ## 查询任务

    * 单个任务：`GET /kling/v1/videos/text2video/{task_id}`。状态依次为 `submitted`、`processing`，最终进入 `succeed` 或 `failed`。
    * 任务列表：`GET /kling/v1/videos/text2video?pageNum=1&pageSize=30`。`pageNum` 范围 1–1000，`pageSize` 范围 1–500。
  </Tab>

  <Tab title="图生视频">
    ## 创建任务

    `POST /kling/v1/videos/image2video`

    使用 `model_name: "kling-3.0"` 根据首帧、尾帧或首尾帧生成视频。请求头必须包含 `Authorization: Bearer <token>` 和 `Content-Type: application/json`。

    <div className="kling-api-example-panel">
      ```bash cURL theme={null}
      curl --request POST \
        --url https://www.anyfast.ai/kling/v1/videos/image2video \
        --header 'Authorization: Bearer YOUR_API_KEY' \
        --header 'Content-Type: application/json' \
        --data '{
          "model_name": "kling-3.0",
          "image": "https://example.com/first-frame.png",
          "prompt": "角色转身走向窗边",
          "duration": "5",
          "mode": "pro",
          "sound": "off"
        }'
      ```

      ```json 200 theme={null}
      {
        "id": "860260753860210752",
        "task_id": "860260753860210752",
        "object": "video",
        "model": "kling-v3",
        "status": "",
        "progress": 0,
        "created_at": 1773130665
      }
      ```
    </div>

    ## 请求头

    <ParamField header="Authorization" type="string" required>
      Bearer 身份验证，格式为 `Bearer YOUR_API_KEY`。
    </ParamField>

    <ParamField header="Content-Type" type="string" default="application/json" required>
      请求数据格式，固定为 `application/json`。
    </ParamField>

    ## 请求参数

    <ParamField body="model_name" type="string" required>Kling 3.0 固定为 `kling-3.0`。</ParamField>
    <ParamField body="image" type="string">首帧 URL 或原始 Base64；与 `image_tail` 至少填写一个。</ParamField>
    <ParamField body="image_tail" type="string">尾帧；不能与运动笔刷或 `camera_control` 同时使用。</ParamField>
    <ParamField body="prompt" type="string">正向提示词，最长 2500 字符；单镜头或智能分镜时使用。</ParamField>
    <ParamField body="negative_prompt" type="string">负向提示词，最长 2500 字符。</ParamField>
    <ParamField body="multi_shot" type="boolean" default={false}>是否生成多镜头视频。</ParamField>
    <ParamField body="shot_type" type="string">多镜头时填写 `customize` 或 `intelligence`。</ParamField>
    <ParamField body="multi_prompt" type="object[]">1–6 个自定义分镜；所有分镜时长之和必须等于 `duration`。</ParamField>
    <ParamField body="element_list" type="object[]">主体引用列表，最多 3 个；与 `voice_list` 互斥。</ParamField>
    <ParamField body="voice_list" type="object[]">音色引用列表，最多 2 个；与 `element_list` 互斥。</ParamField>
    <ParamField body="sound" type="string" default="off">`on` 或 `off`；引用音色时必须为 `on`。</ParamField>
    <ParamField body="cfg_scale" type="number" default={0.5}>提示词相关性，范围 0–1。</ParamField>
    <ParamField body="mode" type="string" default="std">`std` 为 720p，`pro` 为 1080p，`4k` 为 4K。</ParamField>
    <ParamField body="static_mask" type="string">静态运动笔刷蒙版。</ParamField>
    <ParamField body="dynamic_masks" type="object[]">动态运动笔刷，最多 6 组。</ParamField>
    <ParamField body="camera_control" type="object">预设或自定义运镜控制。</ParamField>
    <ParamField body="duration" type="string" default="5">视频时长，可选 3–15 秒。</ParamField>
    <ParamField body="watermark_info" type="object">通过 `enabled` 控制平台水印。</ParamField>

    <ParamField body="multi_prompt[].index" type="integer" required>分镜序号，从 1 开始。</ParamField>
    <ParamField body="multi_prompt[].prompt" type="string" required>当前分镜提示词，最长 512 字符。</ParamField>
    <ParamField body="multi_prompt[].duration" type="string" required>当前分镜时长，至少 1 秒；总和必须等于顶层 `duration`。</ParamField>
    <ParamField body="element_list[].element_id" type="integer" required>主体管理接口返回的主体 ID。</ParamField>
    <ParamField body="voice_list[].voice_id" type="string" required>音色管理接口返回的音色 ID。</ParamField>
    <ParamField body="dynamic_masks[].mask" type="string" required>动态蒙版 URL 或原始 Base64。</ParamField>
    <ParamField body="dynamic_masks[].trajectories" type="object[]" required>运动轨迹坐标列表。</ParamField>
    <ParamField body="dynamic_masks[].trajectories[].x" type="integer" required>横坐标，原点位于左下角。</ParamField>
    <ParamField body="dynamic_masks[].trajectories[].y" type="integer" required>纵坐标，原点位于左下角。</ParamField>
    <ParamField body="camera_control.type" type="string" required>`simple` 或四种预设复合运镜之一。</ParamField>
    <ParamField body="camera_control.config" type="object">`simple` 运镜配置；六个方向参数只能有一个非 0。</ParamField>
    <ParamField body="watermark_info.enabled" type="boolean" default={false}>是否添加平台水印。</ParamField>

    ## 创建响应

    <ResponseField name="id" type="string">AnyFast 任务 ID。</ResponseField>
    <ResponseField name="task_id" type="string">任务 ID，与 `id` 相同。</ResponseField>
    <ResponseField name="object" type="string">对象类型，固定为 `video`。</ResponseField>
    <ResponseField name="model" type="string">实际调用的模型。</ResponseField>
    <ResponseField name="status" type="string">初始任务状态。</ResponseField>
    <ResponseField name="progress" type="integer">初始进度。</ResponseField>
    <ResponseField name="created_at" type="integer">创建 Unix 时间戳。</ResponseField>

    ### 图片要求

    * `image` 和 `image_tail` 支持可公开访问的 URL，或不带 `data:image/...;base64,` 前缀的原始 Base64。
    * 支持 JPG、JPEG、PNG，单张不超过 10 MB，宽高均不小于 300 px，宽高比范围为 1:2.5 至 2.5:1。
    * `image` 和 `image_tail` 至少填写一个，不能同时为空。
    * `image_tail`、运动笔刷（`static_mask` / `dynamic_masks`）和 `camera_control` 三类能力互斥，只能选择其中一类。

    ### 多镜头分镜

    `multi_shot: true` 时必须设置 `shot_type`：

    * `customize`：使用 `multi_prompt` 提供 1–6 个分镜。
    * `intelligence`：使用 `prompt` 自动生成分镜。
    * 每个 `multi_prompt[].prompt` 最长 512 字符。
    * 每个分镜至少 1 秒，且所有 `multi_prompt[].duration` 之和必须等于顶层 `duration`。

    ```json theme={null}
    {
      "multi_shot": true,
      "shot_type": "customize",
      "multi_prompt": [
        {"index": 1, "prompt": "角色抬头看向窗外", "duration": "2"},
        {"index": 2, "prompt": "角色起身走向窗边", "duration": "3"}
      ],
      "duration": "5"
    }
    ```

    ### 主体与音色

    * `element_list` 最多包含 3 个主体，每项填写主体库返回的 `element_id`。
    * `voice_list` 最多包含 2 个音色，每项填写音色管理接口返回的 `voice_id`；不要使用 Lip-Sync 接口的音色 ID。
    * `element_list` 与 `voice_list` 不能同时使用。
    * 在提示词中按数组顺序使用 `<<<voice_1>>>`、`<<<voice_2>>>` 引用音色，并将 `sound` 设置为 `on`。

    ### 运动笔刷

    * `static_mask` 和 `dynamic_masks[].mask` 支持 URL 或原始 Base64，格式要求与 `image` 相同。
    * 蒙版宽高比必须与 `image` 一致；静态蒙版和所有动态蒙版的分辨率必须一致。
    * `dynamic_masks` 最多 6 组，每组包含 `mask` 和 `trajectories`。
    * 生成 5 秒视频时，每条轨迹包含 2–77 个坐标点；坐标原点位于图片左下角，按输入顺序连接。

    ### 运镜控制

    | `camera_control.type` | 行为                  |
    | --------------------- | ------------------- |
    | `simple`              | 使用 `config` 自定义简单运镜 |
    | `down_back`           | 镜头下降并后退             |
    | `forward_up`          | 镜头前进并上仰             |
    | `right_turn_forward`  | 镜头右转后前进             |
    | `left_turn_forward`   | 镜头左转后前进             |

    `type: "simple"` 时，在以下六项中只能设置一个非 0 值，其余必须为 0；每项范围均为 -10 到 10：

    | 字段           | 负值    | 正值    |
    | ------------ | ----- | ----- |
    | `horizontal` | 向左平移  | 向右平移  |
    | `vertical`   | 向下平移  | 向上平移  |
    | `pan`        | 向左摇摄  | 向右摇摄  |
    | `tilt`       | 向下俯仰  | 向上俯仰  |
    | `roll`       | 逆时针滚转 | 顺时针滚转 |
    | `zoom`       | 拉远    | 拉近    |

    <Card title="完整请求参数" icon="code" href="/zh/api-reference/model-api/kuaishou/kling-v3-i2v">
      在交互式 API 页面中填写并调试完整请求体。
    </Card>

    ## 查询任务

    ### 查询单个任务

    `GET /kling/v1/videos/image2video/{task_id}`

    ```bash theme={null}
    curl https://www.anyfast.ai/kling/v1/videos/image2video/860260753860210752 \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```

    <ParamField path="task_id" type="string" required>创建任务接口返回的任务 ID。</ParamField>

    查询结果包含 AnyFast 外层 `code`、`message` 和 `data`。`data` 中包含 `task_id`、`action`、`status`、`fail_reason`、`submit_time`、`start_time`、`finish_time`、`progress`，以及可灵旧版原始响应 `data`。原始响应中的 `task_status` 为 `submitted`、`processing`、`succeed` 或 `failed`；成功时 `task_result.videos[]` 包含 `id`、`url`、`watermark_url` 和 `duration`。

    ### 查询任务列表

    `GET /kling/v1/videos/image2video?pageNum=1&pageSize=30`

    | 查询参数       | 默认值  | 范围     |
    | ---------- | ---- | ------ |
    | `pageNum`  | `1`  | 1–1000 |
    | `pageSize` | `30` | 1–500  |

    列表响应返回分页任务数组，每项字段与单任务查询一致。
  </Tab>

  <Tab title="Omni 视频生成">
    ## 创建任务

    `POST /kling/v1/videos/omni-video`

    使用 `model_name: "kling-3.0-omni"`，结合提示词、图片、视频和主体完成视频生成或编辑。

    <div className="kling-api-example-panel">
      ```bash cURL theme={null}
      curl --request POST \
        --url https://www.anyfast.ai/kling/v1/videos/omni-video \
        --header 'Authorization: Bearer YOUR_API_KEY' \
        --header 'Content-Type: application/json' \
        --data '{
          "model_name": "kling-3.0-omni",
          "prompt": "<<<image_1>>> 中的角色走进雨中的霓虹街道",
          "image_list": [
            {"image_url": "https://example.com/character.png"}
          ],
          "duration": "5",
          "mode": "pro",
          "aspect_ratio": "16:9"
        }'
      ```

      ```json 200 theme={null}
      {"id":"860260753860210752","task_id":"860260753860210752","object":"video","model":"kling-v3-omni","status":"","progress":0,"created_at":1773130665}
      ```
    </div>

    ## 请求头

    <ParamField header="Authorization" type="string" required>Bearer 身份验证，格式为 `Bearer YOUR_API_KEY`。</ParamField>
    <ParamField header="Content-Type" type="string" default="application/json" required>请求数据格式，固定为 `application/json`。</ParamField>

    ## 请求参数

    <ParamField body="model_name" type="string" required>固定为 `kling-3.0-omni`。</ParamField>
    <ParamField body="prompt" type="string">最长 2500 字符；用 `<<<image_1>>>`、`<<<video_1>>>`、`<<<element_1>>>` 引用素材。</ParamField>
    <ParamField body="image_list" type="object[]">参考图片、首帧或尾帧列表。</ParamField>
    <ParamField body="video_list" type="object[]">参考视频列表，最多 1 个；每项包含 `video_url`、`refer_type` 和 `keep_original_sound`。</ParamField>
    <ParamField body="element_list" type="object[]">主体列表；数量受是否传入参考视频影响。</ParamField>
    <ParamField body="multi_shot" type="boolean" default={false}>是否生成多镜头视频。</ParamField>
    <ParamField body="shot_type" type="string">多镜头时填写 `customize` 或 `intelligence`。</ParamField>
    <ParamField body="multi_prompt" type="object[]">1–6 个自定义分镜。</ParamField>
    <ParamField body="mode" type="string" default="pro">`std`、`pro` 或 `4k`。</ParamField>
    <ParamField body="aspect_ratio" type="string">`16:9`、`9:16` 或 `1:1`；无首帧且非视频编辑时填写。</ParamField>
    <ParamField body="duration" type="string" default="5">3–15 秒；`refer_type: "base"` 时不生效。</ParamField>
    <ParamField body="sound" type="string" default="off">生成音效；存在 `video_list` 时必须为 `off`。</ParamField>
    <ParamField body="watermark_info" type="object">通过 `enabled` 控制平台水印。</ParamField>

    <ParamField body="image_list[].image_url" type="string" required>参考图片 URL 或原始 Base64。</ParamField>
    <ParamField body="image_list[].type" type="string">`first_frame` 或 `end_frame`；尾帧必须与首帧同时使用。</ParamField>
    <ParamField body="video_list[].video_url" type="string" required>参考视频 URL。</ParamField>
    <ParamField body="video_list[].refer_type" type="string" default="base">`base` 为基于原视频编辑，`feature` 为特征参考。</ParamField>
    <ParamField body="video_list[].keep_original_sound" type="string">是否保留原视频声音，可选 `yes` 或 `no`。</ParamField>
    <ParamField body="element_list[].element_id" type="integer" required>主体管理接口返回的主体 ID。</ParamField>
    <ParamField body="multi_prompt[].index" type="integer" required>分镜序号，从 1 开始。</ParamField>
    <ParamField body="multi_prompt[].prompt" type="string" required>当前分镜提示词，最长 512 字符。</ParamField>
    <ParamField body="multi_prompt[].duration" type="string" required>当前分镜时长，至少 1 秒。</ParamField>
    <ParamField body="watermark_info.enabled" type="boolean" default={false}>是否添加平台水印。</ParamField>

    ## 创建响应

    <ResponseField name="id" type="string">AnyFast 任务 ID。</ResponseField>
    <ResponseField name="task_id" type="string">任务 ID，与 `id` 相同。</ResponseField>
    <ResponseField name="object" type="string">固定为 `video`。</ResponseField>
    <ResponseField name="model" type="string">`kling-v3-omni`。</ResponseField>
    <ResponseField name="status" type="string">初始任务状态。</ResponseField>
    <ResponseField name="progress" type="integer">初始进度。</ResponseField>
    <ResponseField name="created_at" type="integer">创建 Unix 时间戳。</ResponseField>

    ### 图片与主体

    * 图片支持 URL 或不带 data URI 前缀的原始 Base64；格式为 JPG、JPEG、PNG，单张不超过 10 MB，宽高均不小于 300 px，宽高比为 1:2.5 至 2.5:1。
    * `image_list[].type` 可设为 `first_frame` 或 `end_frame`；尾帧必须与首帧同时使用。
    * 无参考视频时，图片与多图主体合计最多 7 个，视频角色主体最多 3 个。
    * 有参考视频时，图片与多图主体合计最多 4 个，视频角色主体最多 1 个。

    ### 参考视频

    参考视频支持 MP4、MOV，时长 3–15.5 秒，大小不超过 200 MB，帧率 24–60 fps，宽高 700–4553 px，总像素不超过 8,294,400，宽高比为 1:2.5 至 2.5:1。

    | `refer_type` | 行为与限制                                          |
    | ------------ | ---------------------------------------------- |
    | `base`       | 基于原视频编辑；沿用原视频时长，顶层 `duration` 不生效；不支持多镜头和首尾帧控制 |
    | `feature`    | 参考原视频内容、动作、风格或运镜；可使用智能多镜头                      |

    `video_list[].keep_original_sound` 控制是否保留原视频声音。只要存在 `video_list`，就不能通过 `sound` 生成新音效。

    <Card title="交互式请求参数" icon="code" href="/zh/api-reference/model-api/kuaishou/kling-v3-omni">
      在交互式 API 页面中填写并调试完整请求体。
    </Card>

    ## 查询任务

    ### 按任务 ID 查询

    `GET /kling/v1/videos/omni-video/{task_id}`

    <ParamField path="task_id" type="string" required>创建接口返回的任务 ID。</ParamField>

    响应包含 AnyFast 外层状态与可灵原始 `task_status`、`task_status_msg`、`task_result.videos[]`、`created_at` 和 `updated_at`。成功视频项包含视频 ID、下载 URL、水印 URL 和时长。

    ### 查询任务列表

    `GET /kling/v1/videos/omni-video?pageNum=1&pageSize=30`

    <ParamField query="pageNum" type="integer" default={1}>页码，范围 1–1000。</ParamField>
    <ParamField query="pageSize" type="integer" default={30}>每页数量，范围 1–500。</ParamField>
  </Tab>

  <Tab title="动作控制">
    ## 创建任务

    `POST /kling/v1/videos/motion-control`

    使用 `model_name: "kling-3.0"`，将动作参考视频中的动作迁移到角色参考图片。

    <div className="kling-api-example-panel">
      ```bash cURL theme={null}
      curl --request POST \
        --url https://www.anyfast.ai/kling/v1/videos/motion-control \
        --header 'Authorization: Bearer YOUR_API_KEY' \
        --header 'Content-Type: application/json' \
        --data '{
          "model_name": "kling-3.0",
          "image_url": "https://example.com/character.png",
          "video_url": "https://example.com/motion.mp4",
          "prompt": "角色在摄影棚中完成参考动作",
          "keep_original_sound": "yes",
          "character_orientation": "image",
          "mode": "pro"
        }'
      ```

      ```json 200 theme={null}
      {"id":"860260753860210752","task_id":"860260753860210752","object":"video","model":"kling-v3","status":"","progress":0,"created_at":1773130665}
      ```
    </div>

    ## 请求头

    <ParamField header="Authorization" type="string" required>Bearer 身份验证，格式为 `Bearer YOUR_API_KEY`。</ParamField>
    <ParamField header="Content-Type" type="string" default="application/json" required>请求数据格式，固定为 `application/json`。</ParamField>

    ## 请求参数

    <ParamField body="model_name" type="string" required>固定为 `kling-3.0`。</ParamField>
    <ParamField body="image_url" type="string" required>角色参考图 URL 或原始 Base64。</ParamField>
    <ParamField body="video_url" type="string" required>动作参考视频 URL。</ParamField>
    <ParamField body="prompt" type="string">补充场景、动作或运镜，最长 2500 字符。</ParamField>
    <ParamField body="element_list" type="object[]">参考主体列表，最多 1 个。</ParamField>
    <ParamField body="keep_original_sound" type="string" default="yes">是否保留参考视频原声，可选 `yes` 或 `no`。</ParamField>
    <ParamField body="character_orientation" type="string" required>角色方向来源，可选 `image` 或 `video`。</ParamField>
    <ParamField body="mode" type="string" required>生成模式，可选 `std` 或 `pro`。</ParamField>
    <ParamField body="watermark_info" type="object">通过 `enabled` 控制平台水印。</ParamField>

    <ParamField body="element_list[].element_id" type="integer" required>主体管理接口返回的主体 ID，最多一个。</ParamField>
    <ParamField body="watermark_info.enabled" type="boolean" default={false}>是否添加平台水印。</ParamField>

    ## 创建响应

    <ResponseField name="id" type="string">AnyFast 任务 ID。</ResponseField>
    <ResponseField name="task_id" type="string">任务 ID，与 `id` 相同。</ResponseField>
    <ResponseField name="object" type="string">固定为 `video`。</ResponseField>
    <ResponseField name="model" type="string">`kling-v3`。</ResponseField>
    <ResponseField name="status" type="string">初始任务状态。</ResponseField>
    <ResponseField name="progress" type="integer">初始进度。</ResponseField>
    <ResponseField name="created_at" type="integer">创建 Unix 时间戳。</ResponseField>

    ### 素材要求

    * 角色参考图支持 JPG、JPEG、PNG，大小不超过 10 MB；宽高 300–65,536 px，宽高比为 1:2.5 至 2.5:1。
    * 动作参考视频支持 MP4、MOV，大小不超过 100 MB，宽高 340–3850 px，时长 3–30 秒。
    * `character_orientation: "image"` 表示角色方向跟随参考图片，参考视频最长 10 秒。
    * `character_orientation: "video"` 表示角色方向跟随参考视频，参考视频最长 30 秒。
    * 引用 `element_list` 中的主体时，角色方向跟随参考视频。

    <Warning>
      如果动作难度较高或速度较快，生成结果可能短于上传视频，因为模型只会提取有效的连续动作片段进行生成；最短提取出 3 秒可用连续动作即可生成。此类情况下已消耗的积分无法退还，建议适当降低动作难度或速度。
    </Warning>

    <Card title="交互式请求参数" icon="code" href="/zh/api-reference/model-api/kuaishou/kling-v3-motion-control">
      在交互式 API 页面中填写并调试完整请求体。
    </Card>

    ## 查询任务

    ### 按任务 ID 查询

    `GET /kling/v1/videos/motion-control/{task_id}`

    <ParamField path="task_id" type="string" required>创建接口返回的任务 ID。</ParamField>

    响应状态及 `task_result.videos[]` 字段与其他可灵旧版视频任务一致。

    ### 查询任务列表

    `GET /kling/v1/videos/motion-control?pageNum=1&pageSize=30`

    <ParamField query="pageNum" type="integer" default={1}>页码，范围 1–1000。</ParamField>
    <ParamField query="pageSize" type="integer" default={30}>每页数量，范围 1–500。</ParamField>
  </Tab>

  <Tab title="主体管理">
    ## 主体接口

    | 操作         | 方法与路径                                    |
    | ---------- | ---------------------------------------- |
    | 创建自定义主体    | `POST /kling/v1/general/custom-elements` |
    | 查询自定义主体列表  | `GET /kling/v1/general/custom-elements`  |
    | 查询官方预置主体列表 | `GET /kling/v1/general/presets-elements` |

    ## 创建自定义主体

    <div className="kling-api-example-panel">
      ```bash cURL theme={null}
      curl --request POST \
        --url https://www.anyfast.ai/kling/v1/general/custom-elements \
        --header 'Authorization: Bearer YOUR_API_KEY' \
        --header 'Content-Type: application/json' \
        --data '{
          "element_name": "my-character",
          "element_description": "视频系列主角",
          "element_frontal_image": "https://example.com/front.png",
          "element_refer_list": [
            {"image_url": "https://example.com/side.png"},
            {"image_url": "https://example.com/close-up.png"}
          ],
          "tag_list": [{"tag_id": "o_102"}]
        }'
      ```

      ```json 200 theme={null}
      {
        "code": 0,
        "message": "string",
        "request_id": "string",
        "data": {
          "element_id": 0,
          "element_name": "string",
          "element_description": "string",
          "element_frontal_image": "image_url_0",
          "element_refer_list": [{"image_url": "image_url_1"}],
          "tag_list": [{"id": "o_102", "name": "Character", "description": "string"}],
          "owned_by": "string"
        }
      }
      ```
    </div>

    ## 请求头

    <ParamField header="Authorization" type="string" required>Bearer 身份验证，格式为 `Bearer YOUR_API_KEY`。</ParamField>
    <ParamField header="Content-Type" type="string" default="application/json" required>请求数据格式，固定为 `application/json`。</ParamField>

    ## 请求体

    <ParamField body="element_name" type="string" required>主体名称，最长 20 个字符。</ParamField>
    <ParamField body="element_description" type="string" required>主体描述，最长 100 个字符。</ParamField>
    <ParamField body="element_frontal_image" type="string" required>主体正面参考图，支持可访问的图片 URL 或不带 data URI 前缀的原始 Base64。</ParamField>
    <ParamField body="element_refer_list" type="object[]" required>主体其他角度的参考图，至少 1 张、最多 3 张。</ParamField>
    <ParamField body="element_refer_list[].image_url" type="string" required>参考图片 URL 或不带 data URI 前缀的原始 Base64。</ParamField>
    <ParamField body="tag_list" type="object[]">主体标签列表，一个主体可以配置多个标签。</ParamField>
    <ParamField body="tag_list[].tag_id" type="string" required>标签 ID：`o_101` 热梗、`o_102` 人物、`o_103` 动物、`o_104` 道具、`o_105` 服饰、`o_106` 场景、`o_107` 特效、`o_108` 其他。</ParamField>

    图片格式支持 JPG、JPEG、PNG，单张不超过 10 MB，宽高均不小于 300 px，宽高比为 1:2.5 至 2.5:1。

    ## 创建响应

    <ResponseField name="code" type="integer">错误码；`0` 表示请求成功。</ResponseField>
    <ResponseField name="message" type="string">错误信息或成功消息。</ResponseField>
    <ResponseField name="request_id" type="string">系统生成的请求 ID，用于跟踪请求和排查问题。</ResponseField>
    <ResponseField name="data.element_id" type="integer">主体 ID，用于支持主体引用的视频接口。</ResponseField>
    <ResponseField name="data.element_name" type="string">主体名称。</ResponseField>
    <ResponseField name="data.element_description" type="string">主体描述。</ResponseField>
    <ResponseField name="data.element_frontal_image" type="string">主体正面参考图地址。</ResponseField>
    <ResponseField name="data.element_refer_list" type="object[]">其他角度参考图列表。</ResponseField>
    <ResponseField name="data.element_refer_list[].image_url" type="string">参考图地址。</ResponseField>
    <ResponseField name="data.tag_list" type="object[]">主体标签列表。</ResponseField>
    <ResponseField name="data.tag_list[].id" type="string">标签 ID。</ResponseField>
    <ResponseField name="data.tag_list[].name" type="string">标签名称。</ResponseField>
    <ResponseField name="data.tag_list[].description" type="string">标签描述。</ResponseField>
    <ResponseField name="data.owned_by" type="string">主体来源；`kling` 表示官方主体，其他值表示创建者 ID。</ResponseField>

    ## 查询自定义主体列表

    `GET /kling/v1/general/custom-elements?pageNum=1&pageSize=30`

    <ParamField query="pageNum" type="integer" default={1}>页码，范围 1–1000。</ParamField>
    <ParamField query="pageSize" type="integer" default={30}>每页数量，范围 1–500。</ParamField>

    响应顶层包含 `code`、`message`、`request_id` 和 `data[]`。每个主体包含创建响应中的全部主体字段，并额外返回 `final_unit_deduction` 表示主体创建任务最终扣减的积分。

    ```json 200 theme={null}
    {
      "code": 0,
      "message": "string",
      "request_id": "string",
      "data": [
        {
          "element_id": 0,
          "element_name": "string",
          "element_description": "string",
          "element_frontal_image": "image_url_0",
          "element_refer_list": [{"image_url": "image_url_1"}],
          "tag_list": [{"id": "o_102", "name": "Character", "description": "string"}],
          "final_unit_deduction": "string",
          "owned_by": "string"
        }
      ]
    }
    ```

    ## 查询官方预置主体列表

    `GET /kling/v1/general/presets-elements?pageNum=1&pageSize=30`

    <ParamField query="pageNum" type="integer" default={1}>页码，范围 1–1000。</ParamField>
    <ParamField query="pageSize" type="integer" default={30}>每页数量，范围 1–500。</ParamField>

    响应结构与自定义主体列表一致，但不包含 `final_unit_deduction`；官方主体的 `owned_by` 为 `kling`。

    ```json 200 theme={null}
    {
      "code": 0,
      "message": "string",
      "request_id": "string",
      "data": [
        {
          "element_id": 0,
          "element_name": "string",
          "element_description": "string",
          "element_frontal_image": "image_url_0",
          "element_refer_list": [{"image_url": "image_url_1"}],
          "tag_list": [{"id": "o_102", "name": "Character", "description": "string"}],
          "owned_by": "kling"
        }
      ]
    }
    ```

    <Note>本页严格使用可灵旧版主体 API。</Note>
  </Tab>

  <Tab title="音色管理">
    ## 音色接口

    | 操作        | 方法与路径                                      |
    | --------- | ------------------------------------------ |
    | 创建自定义音色   | `POST /kling/v1/general/custom-voices`     |
    | 查询单个自定义音色 | `GET /kling/v1/general/custom-voices/{id}` |
    | 查询自定义音色列表 | `GET /kling/v1/general/custom-voices`      |
    | 查询预置音色列表  | `GET /kling/v1/general/presets-voices`     |
    | 删除自定义音色   | `POST /kling/v1/general/delete-voices`     |

    ### 创建自定义音色

    `voice_name` 最长 20 字符。`voice_url` 与 `video_id` 至少填写一个：

    <div className="kling-api-example-panel">
      ```bash cURL theme={null}
      curl --request POST \
        --url https://www.anyfast.ai/kling/v1/general/custom-voices \
        --header 'Authorization: Bearer YOUR_API_KEY' \
        --header 'Content-Type: application/json' \
        --data '{
          "voice_name": "narrator",
          "voice_url": "https://example.com/voice.mp3"
        }'
      ```

      ```json 200 theme={null}
      {"code":0,"message":"SUCCEED","request_id":"request-id","data":{"task_id":"850087542757535834","task_status":"submitted"}}
      ```
    </div>

    ## 请求头

    <ParamField header="Authorization" type="string" required>Bearer 身份验证，格式为 `Bearer YOUR_API_KEY`。</ParamField>
    <ParamField header="Content-Type" type="string" default="application/json" required>请求数据格式，固定为 `application/json`。</ParamField>

    ## 请求参数

    <ParamField body="voice_name" type="string" required>自定义音色名称，最长 20 个字符。</ParamField>
    <ParamField body="voice_url" type="string">公开可访问的 MP3、WAV、MP4 或 MOV 地址；与 `video_id` 至少填写一个。</ParamField>
    <ParamField body="video_id" type="string">符合条件的历史生成视频 ID；与 `voice_url` 至少填写一个。</ParamField>

    * `voice_url` 支持公开可访问的 MP3、WAV、MP4 或 MOV；素材应仅包含一个清晰人声，时长 5–30 秒。
    * `video_id` 可引用符合条件的历史生成视频；音频同样应只有一个清晰人声，时长 5–30 秒。

    创建接口返回任务 ID。查询结果的 `task_status` 可能为 `submitted`、`processing`、`succeed` 或 `failed`；成功后从结果中取得 `voice_id` 和试听地址。

    ## 创建响应

    <ResponseField name="code" type="integer">`0` 表示请求成功。</ResponseField>
    <ResponseField name="message" type="string">响应消息。</ResponseField>
    <ResponseField name="request_id" type="string">请求 ID。</ResponseField>
    <ResponseField name="data.task_id" type="string">音色创建任务 ID。</ResponseField>
    <ResponseField name="data.task_status" type="string">`submitted`、`processing`、`succeed` 或 `failed`。</ResponseField>
    <ResponseField name="data.task_status_msg" type="string">失败时的原因。</ResponseField>
    <ResponseField name="data.task_result.voices" type="object[]">成功生成的音色列表。</ResponseField>

    ### 查询单个自定义音色

    `GET /kling/v1/general/custom-voices/{id}`

    <ParamField path="id" type="string" required>创建自定义音色接口返回的任务 ID。</ParamField>

    成功结果中的音色项包含 `voice_id`、`voice_name`、`trial_url` 和 `owned_by`。

    ### 查询自定义音色列表

    `GET /kling/v1/general/custom-voices?pageNum=1&pageSize=30`

    <ParamField query="pageNum" type="integer" default={1}>页码，范围 1–1000。</ParamField>
    <ParamField query="pageSize" type="integer" default={30}>每页数量，范围 1–1000。</ParamField>

    ### 查询官方预置音色列表

    `GET /kling/v1/general/presets-voices?pageNum=1&pageSize=30`

    <ParamField query="pageNum" type="integer" default={1}>页码，范围 1–1000。</ParamField>
    <ParamField query="pageSize" type="integer" default={30}>每页数量，范围 1–1000。</ParamField>

    官方预置音色的 `owned_by` 固定为 `kling`，可直接用于视频生成，但不能删除。

    ### 删除自定义音色

    `POST /kling/v1/general/delete-voices`

    <ParamField body="voice_id" type="string" required>需要删除的自定义音色 ID。</ParamField>

    删除接口返回 `code`、`message`、`request_id` 和删除任务数据。

    <Card title="音色管理 API" icon="microphone" href="/zh/api-reference/model-api/kuaishou/kling-voice-management">
      进入各音色操作的交互式参数页面。
    </Card>
  </Tab>
</Tabs>

<Note>
  本组接口使用可灵旧版请求结构。AnyFast 在旧版接口路径前增加 `/kling` 路由前缀，接口名称和请求字段保持旧版结构。
</Note>

<script src="/feedback.js" />
