• 简体中文
  • 动作控制(Motion Control)

    用一段「动作参考视频」驱动「形象参考图」中的人物,生成动作与参考视频一致的视频;kling-video-motion-control-v3.0 还可通过元素(Element)直接指定定制角色。本接口无 duration 参数,输出时长跟随动作参考视频。

    端点

    • 提交:POST /kling/v1/videos/text2video(与文生视频共用入口,网关按模型自动路由到上游动作控制端点)
    • 查询:GET /kling/v1/videos/text2video/{task_id},见查询与下载

    模型:kling-video-motion-control-v3.0、kling-video-motion-control-v2.6。

    请求体

    字段类型必填说明
    modelstring是动作控制模型名(model_name 同样有效)
    metadata.contentsarray是参考素材合集:形象参考图(image)与动作参考视频(video)各恰好 1 项,可选提示词(prompt)与参考主体(element),子字段见下表
    metadata.character_orientationstring是生成视频中人物的朝向:image(与形象参考图中人物一致)/ video(与动作参考视频中人物一致)
    resolutionstring否清晰度:720p(默认)/ 1080p(顶层或 metadata 均可)
    audiostring否声音:original(保留参考视频原声,默认)/ off(顶层或 metadata 均可)
    metadata.optionsobject否通用配置:external_task_id(自定义任务 ID)、watermark_info({"enabled":true} 开「AI生成」水印)

    metadata.contents 数组元素:

    type必填字段说明
    prompttext(≤ 2500 字符)文本提示词,可为画面增加元素、实现运镜效果;建议不描述动作,动作由参考视频决定
    imageurl形象参考图,URL 或 Base64。jpg / jpeg / png,≤ 50MB,宽高均 ≥ 300px,宽高比 1:2.5 ~ 2.5:1
    videourl动作参考视频,仅 URL。mp4 / mov,≤ 100MB,宽高 340 ~ 3850px,不短于 3 秒
    elementelement_id + id参考主体(元素管理创建的元素),仅 v3.0 支持、最多 1 个;id 为自取索引,prompt 中用 @id 引用
    NOTE

    动作参考视频的时长上限与 character_orientation 相关:image(朝向与图片一致)参考视频最长 10 秒;video(朝向与视频一致)最长 30 秒。动作过快或难度高时,可能生成短于上传时长的视频(模型仅提取有效动作时长,最短提取 3 秒即可生成),计费以输出视频时长为准。

    请求示例

    cURL
    Python
    Node.js
    curl -X POST https://api-model.shuntianchuang.cn/kling/v1/videos/text2video \
      -H "Authorization: Bearer sk-你的令牌" \
      -H "Content-Type: application/json" \
      -d '{
        "model_name": "kling-video-motion-control-v3.0",
        "resolution": "720p",
        "audio": "original",
        "metadata": {
          "character_orientation": "video",
          "contents": [
            {"type": "prompt", "text": "The girl is wearing casual clothes, standing naturally"},
            {"type": "image", "url": "https://example.com/character.png"},
            {"type": "video", "url": "https://example.com/motion.mp4"}
          ]
        }
      }'
    WARNING

    形象参考图:人物比例尽量与参考视频中人物一致(避免全身动作驱动半身人物),人物需露出清晰的上半身或全身肢体及头部,避免遮挡与倒立、平卧等极端朝向;支持真实 / 风格化角色。动作参考视频:建议单人动作(多人时取画面占比最大者)、真人动作、一镜到底且角色始终在画面中,避免切镜与运镜(否则会被截取)。素材 URL 必须是公网可直接下载的直链。

    响应体

    提交成功返回可灵格式任务对象(同提交任务响应体),data.task_id 用于查询。查询状态流转、task_result.videos 结构与计费回显(final_unit_deduction)均与文生 / 图生视频一致,见查询与下载。

    响应示例

    {
      "code": 0,
      "message": "SUCCEED",
      "data": {
        "task_id": "task_xxxxxxxx",
        "task_status": "submitted",
        "task_status_msg": "",
        "create_time": 1790577808000,
        "update_time": 1790577808000
      },
      "task_id": "task_xxxxxxxx"
    }
    NOTE

    实测口径(v3.0,720p + audio:"original",约 3 分钟出片):成片分辨率跟随 720p 档(1264×720,画幅跟随素材比例)、时长跟随动作参考视频(5.08s → 5.03s)、final_unit_deduction 450000。成片为上游签名直链,约 45 分钟后失效,请及时下载转存;参考视频本身无声时,audio:"original" 输出同样无声。模型名与价格以模型广场为准,计费按任务完成时的实际用量结算(失败自动退还)。