跳转到主要内容
POST
/
kling
/
v1
/
videos
/
motion-control
可灵运镜控制视频任务 (kling-v3)
curl --request POST \
  --url https://api.powertokens.ai/kling/v1/videos/motion-control \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model_name": "kling-v3",
  "image_url": "https://example.com/character.png",
  "video_url": "https://example.com/motion.mp4",
  "character_orientation": "video",
  "mode": "std"
}
'
{
  "code": 123,
  "message": "<string>",
  "data": {
    "task_id": "<string>",
    "task_status": "submitted",
    "task_info": {
      "external_task_id": "<string>"
    },
    "created_at": 123,
    "updated_at": 123
  },
  "request_id": "<string>"
}

授权

​
Authorization
string
header
必填

在请求头中传入 Authorization: Bearer <token>。

请求体

application/json
​
model_name
enum<string>
必填

模型名称

可用选项:
kling-v3
​
image_url
string
必填

参考图像，生成视频中的人物、背景等元素均以参考图为准

  • 视频内容需满足以下要求：
    • 人物比例尽量与参考动作比例一致，尽量避免全身动作驱动半身人物进行生成
    • 人物需要露出清晰的上半身或全身的肢体及头部，避免遮挡
    • 画面中人物避免存在极端朝向，比如倒立、平卧等。人物占画面比例不得太低
    • 支持真实/风格化的角色（包括人物/类人动物/部分纯动物/部分类人肢体比例的角色）通过
  • 支持传入图片 Base64 编码或图片 URL（确保可访问）
  • 注意：若您使用 Base64 方式，请不要在 Base64 编码字符串前添加任何前缀（如 data:image/png;base64,），直接传递 Base64 编码后的字符串即可。
  • 正确的 Base64 编码参数：

iVBORw0KGgoAAAANSUhEUgAAAAUA...

  • 错误的 Base64 编码参数（包含 data: 前缀）：

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...

  • 图片格式支持 .jpg / .jpeg / .png
  • 图片文件大小不能超过 10MB，图片宽高尺寸介于 300px～65536px，图片宽高比介于 1:2.5 ~ 2.5:1 之间
​
video_url
string
必填

参考视频的获取链接。生成视频中的人物动作与参考视频一致。

  • 视频内容需满足以下要求：
    • 人物需要露出清晰的上半身或全身的全部肢体及头部，避免遮挡
    • 建议上传 1 人动作视频，2 人及以上会取画面占比最大的人物动作进行生成
    • 推荐使用真人动作，部分风格化的人物/类人肢体比例可以通过
    • 动作视频一镜到底，角色始终出现在画面中，避免切镜、运镜等。否则会被截取
    • 动作避免过快，相对平稳的动作生成效果更佳
  • 视频文件支持 .mp4/.mov，文件大小不超过 100MB，仅支持长宽的边长均位于 340px~3850px 之间，上述校验不通过会返回错误码等信息
  • 视频时长下限不短于 3 秒，时长上限与人物朝向参考（character_orientation）有关：
    • 当人物朝向与视频中人物一致时，视频时长最长可达 30 秒
    • 当人物朝向与图片中人物一致时，视频时长最长可达 10 秒
  • 如果您的动作难度比较高、速度比较快，有一定概率生成不足上传视频时长的结果，因为模型只能提取有效动作时长进行生成，最短提取出 3s 可用连续动作即可生成。请注意，因此消耗的积分将无法退还，建议适当调整动作难度与速度
  • 系统会校验视频内容，如有问题会返回错误码等信息
​
character_orientation
enum<string>
必填

生成视频中人物的朝向，可选择与图片一致或与视频一致

  • image：与图片中人物朝向一致；此时参考视频时长不得超过 10 秒
  • video：与视频中人物朝向一致；此时参考视频时长不得超过 30 秒
  • 引用主体时，生成的视频暂时只能参考视频中的人物朝向
可用选项:
image,
video
​
mode
enum<string>
必填

生成视频的模式

  • std：标准模式（标准），基础模式，性价比高
  • pro：专家模式（高品质），高表现模式，生成视频质量更佳
可用选项:
std,
pro
​
prompt
string

文本提示词，可包含正向描述和负向描述

  • 可通过提示词为画面增加元素、实现运镜效果等
Maximum string length: 2500
​
element_list
object[]

主体参考列表，基于主体库中的主体 ID 配置。

  • 用 key:value 承载，如下：
"element_list":[{ "element_id": 829836802793406551 }]```

- 引用主体时，生成的视频暂时只能参考视频中的人物朝向
- 暂时仅支持引入1个主体
​
keep_original_sound
enum<string>
默认值:yes

是否保留视频原声。

可用选项:
yes,
no
​
watermark_info
object

是否同时生成含水印的结果。

​
callback_url
string

本次任务结果回调通知地址，如果配置，服务端会在任务状态发生变更时主动通知

​
external_task_id
string

自定义任务ID

响应

任务已受理。

​
code
integer
必填

可灵响应码。0 表示任务已被接受。

​
message
string
必填

可灵响应消息。

​
data
object
必填
​
request_id
string

上游请求标识符（如有提供）。