Kling 3.0 Motion Control

Kling 3.0 Motion Control 是动作迁移模型:把参考视频中的动作迁移到参考图片中的角色身上,同时保留角色的身份、外观与背景,生成一段你的角色完成参考动作的视频。输出支持 720P / 1080P,最长 30 秒。

模型

模型名称	模式
`kling-v3-motion-control`	参考图 + 参考视频生成动作迁移视频

定价

按输出视频秒数(= 参考视频时长)× 分辨率计费:

分辨率	积分/秒
`720p`	30
`1080p`	40

参考视频时长由服务端自动探测用于计费,探测失败(URL 不可访问或格式不支持)时任务创建会返回 400 错误且不扣积分。积分在创建任务时预扣,任务失败会自动退还。

创建任务

POST https://api.aivideoapi.ai/v1/videos/generations

请求体

字段	类型	必填	说明
`model`	string	是	`kling-v3-motion-control`
`input`	object	是	生成参数
`callback_url`	string	否	接收任务完成/失败通知的 URL

Input 参数

字段	类型	必填	说明
`input_urls`	string[]	是	参考图片 URL。JPG/JPEG/PNG,≤ 10MB,≥ 300px,宽高比在 2:5 到 5:2 之间。输出中的角色与背景基于该图片。
`video_urls`	string[]	是	参考视频 URL。MP4/MOV,≤ 100MB,3-30 秒。输出中的角色动作与该视频一致。
`character_orientation`	string	否	`image`:保持图片中人物的朝向(输出最长 10 秒);`video`:与视频中角色的朝向一致(输出最长 30 秒)。默认 `video`。
`mode`	string	否	输出分辨率:`720p`(默认)或 `1080p`。
`prompt`	string	否	场景/动作描述,最长 2500 字符。默认值:"No distortion, the character's movements are consistent with the video."。

不支持 duration 参数:输出视频时长跟随参考视频,并受 character_orientation 限制(image ≤ 10 秒,video ≤ 30 秒)。所有媒体必须为公网 HTTP(S) URL。

示例

基础动作迁移

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-motion-control",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "input_urls": ["https://example.com/character.png"],
      "video_urls": ["https://example.com/reference-motion.mp4"],
      "character_orientation": "video",
      "mode": "720p"
    }
  }'

1080P + 提示词

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-motion-control",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "input_urls": ["https://example.com/dancer.png"],
      "video_urls": ["https://example.com/dance-clip.mp4"],
      "character_orientation": "image",
      "mode": "1080p",
      "prompt": "角色流畅地完成舞蹈动作,无形变"
    }
  }'

响应

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "8b6a5162-5c91-4a42-8e80-4c8ef5486f24"
  }
}

查询任务

curl https://api.aivideoapi.ai/v1/tasks/{taskId} \
  -H "Authorization: Bearer sk-your-api-key"

状态变化:pending -> processing -> completed 或 failed。

任务失败时,预扣的积分会自动退还。

回调 (Callback)

创建任务时传入 callback_url,系统会在任务完成或失败时自动向你的 URL 发送 POST 请求。请求头与重试策略详见回调说明。

任务完成时回调

{
  "id": "8b6a5162-5c91-4a42-8e80-4c8ef5486f24",
  "status": "completed",
  "model": "kling-v3-motion-control",
  "created_at": 1781136227,
  "completed_at": 1781136589,
  "output": {
    "urls": [
      "https://file.aivideoapi.ai/videos/2026/06/15/abc.mp4"
    ],
    "metadata": {
      "model": "kling-3.0/motion-control"
    }
  }
}

任务失败时回调

{
  "id": "57c8772c-f834-46f3-9b7d-81f92e104050",
  "status": "failed",
  "model": "kling-v3-motion-control",
  "created_at": 1781136227,
  "error": {
    "code": "upstream_error",
    "message": "Video generation failed"
  }
}

重要说明

收到回调后请尽快返回 2xx 状态码(建议 3 秒内)。返回非 2xx 或超时(10 秒)将触发重试,最多 3 次(间隔分别为 3 分钟、10 分钟)。
业务侧应根据 X-Task-Id 做幂等处理,避免同一任务重复入库。
任务最终状态以 GET /v1/tasks/{taskId} 查询为准;如果 3 次回调都失败,仍可主动轮询兜底。

常见错误码

请求失败时，API 返回 JSON 格式的错误响应：

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your credit balance is too low. Please top up.",
    "type": "billing_error"
  }
}

错误码一览

HTTP 状态码	错误码	类型	说明
400	`invalid_request`	invalid_request_error	缺少必填参数或参数无效
401	`invalid_api_key`	authentication_error	API Key 无效、已禁用或已删除
402	`insufficient_credits`	billing_error	积分余额不足，请充值
403	`ip_not_allowed`	permission_error	请求 IP 不在 Key 的白名单中
404	`model_not_found`	invalid_request_error	模型不存在或已停用
404	`task_not_found`	invalid_request_error	任务 ID 不存在
429	`rate_limit_exceeded`	rate_limit_error	请求过于频繁，请降低频率
429	`spend_limit_exceeded`	billing_error	达到 Key 的消费限额（每小时/每天/总量）
500	`internal_error`	api_error	服务器内部错误
503	`upstream_error`	upstream_error	上游 AI 服务返回错误

常见场景

invalid_request (400)

缺少必填字段或参数格式错误时返回。

{
  "error": {
    "code": "invalid_request",
    "message": "'model' is required.",
    "type": "invalid_request_error"
  }
}

insufficient_credits (402)

积分不足。可通过 GET /v1/credits 查询余额，前往 Dashboard > Billing 充值。

invalid_api_key (401)

可能原因：

Key 不以 sk- 开头
Key 已被禁用或删除
用户账户已被封禁

upstream_error (503)

上游 AI 服务返回错误，可能原因：

输入内容包含敏感或违规信息
上游服务暂时不可用
请求参数不被上游支持

因上游错误导致任务失败时，预扣积分会自动退还。