⌘K

Kirin V3 Motion Control

kirin_v3_motion_control

Kirin V3 动作控制视频生成：通过图片与参考视频创作动作控制视频.

认证

authorization string 必填

所有 API 均使用 Bearer Token 鉴权

获取 API Key：

访问 API Key 管理页面 获取 API Key

用法：

将以下 Header 添加到请求中：

Authorization: Bearer YOUR_API_KEY

参数

model string 必填

请求使用的模型 ID

值: kirin_v3_motion_control

prompt string

文本提示词, 可包含正向描述和负向描述, 可通过提示词为画面增加元素、实现运镜效果等

注：不能超过 2500 个字符

image_url string 必填

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

图片要求：
支持传入图片 Base64 编码或图片 URL（确保可访问）
注意：若使用 Base64 方式, 请不要在 Base64 编码字符串前添加任何前缀（如 data:image/png;base64,）, 直接传递 Base64 编码后的字符串即可
图片格式支持 .jpg / .jpeg / .png
图片文件大小不能超过 10MB, 图片宽高尺寸介于 300px～65536px, 图片宽高比介于 1:2.5 ～ 2.5:1 之间

内容要求：
人物比例尽量与参考动作比例一致, 尽量避免全身动作驱动半身人物进行生成
人物需要露出清晰的上半身或全身的肢体及头部, 避免遮挡
画面中人物避免存在极端朝向, 比如倒立、平卧等. 人物占画面比例不得太低
支持真实/风格化的角色（包括人物/类人动物/部分纯动物/部分类人肢体比例的角色）

video_url string 必填

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

视频要求：
视频文件支持 .mp4 / .mov, 文件大小不超过 100MB, 仅支持长宽的边长均位于 340px～3850px 之间
视频时长下限不短于 3 秒
当 character_orientation 为 image 时, 视频时长最长可达 10 秒
当 character_orientation 为 video 时, 视频时长最长可达 30 秒

内容要求：
人物需要露出清晰的上半身或全身的全部肢体及头部, 避免遮挡
建议上传 1 人动作视频, 2 人及以上会取画面占比最大的人物动作进行生成
推荐使用真人动作, 部分风格化的人物/类人肢体比例可以通过
动作视频一镜到底, 角色始终出现在画面中, 避免切镜、运镜等
动作避免过快, 相对平稳的动作生成效果更佳

element_list array

主体参考列表, 基于主体库中主体的 ID 配置, 暂时仅支持引入 1 个主体

创建主体请参考：kirin_custom_elements

"element_list": [
  { "element_id": 829836802793406551 }
]

注：引用主体时, 生成的视频暂时只能参考视频中的人物朝向

element_id long 必填

主体库中主体的 ID

keep_original_sound string

是否保留视频原声

默认值: yes

可选值: yes、no

character_orientation string 必填

生成视频中人物的朝向

可选值:
image：与图片中人物朝向一致；此时参考视频时长不得超过 10 秒
video：与视频中人物朝向一致；此时参考视频时长不得超过 30 秒

注：引用主体时, 生成的视频暂时只能参考视频中的人物朝向

mode string 必填

生成视频的模式

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

watermark_info object

是否同时生成含水印的结果, 暂不支持自定义水印

enabled boolean

true：生成含水印的结果
false：不生成

callback_url string

回调 URL

external_task_id string

自定义任务 ID

用户自定义任务 ID, 传入不会覆盖系统生成的任务 ID, 但支持通过该 ID 进行任务查询

注：单用户下需要保证唯一性

轮询

由于结果生成需要时间，您需要在创建任务后轮询任务状态

初始响应只返回任务 ID 和初始状态等信息，最终生成结果需通过使用该任务 ID 轮询任务状态接口获取

轮询请求与响应示例见右侧

响应格式

error object

错误信息, 仅在状态为 failed 时存在

code string

错误码

message string

详细错误信息

output array

生成结果, 仅在状态为 completed 时存在

content array

生成的资源内容列表

type string

资源类型

值: image｜video

url string

处理后的资源 URL

jobId string

远端任务 ID

usage object

使用统计, 仅在状态为 completed 时存在

cost string

总费用（美元）

discount number

折扣金额

metadata object

元数据信息