⌘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

错误码。建议按该字段进行程序化失败处理。

error_message string

详细错误信息，用于说明任务失败原因。

output array

生成结果。仅在任务状态为 completed 时返回。

content array

生成内容列表。

type string

资源类型，例如 image 或 video。

url string

生成资源 URL。

usage object

用量信息。仅在任务状态为 completed 时返回。

cost string

总费用，单位为美元。

discount number

折扣金额。