Kirin V3 Omni Video | Vtrix API Docs

接口提示

使用视频参考能力时, 仅支持 3-10 秒

认证

authorization `string` 必填

所有 API 均使用 Bearer Token 鉴权

获取 API Key：

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

用法：

将以下 Header 添加到请求中：

Authorization: Bearer YOUR_API_KEY

参数

model `string` 必填

请求使用的模型 ID.

值：kirin_v3_omni_video

multi_shot `boolean`

是否生成多镜头视频

当前参数为 true 时, prompt 参数无效

当前参数为 false 时, shot_type 参数及 multi_prompt 参数无效

默认值: false

shot_type `string`

分镜方式

当 multi_shot 参数为 true 时, 当前参数必填

选项: customize

prompt `string`

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

可将提示词模板化来满足不同的视频生成需求

Video O3 模型可通过 Prompt 与主体、图片、视频等内容实现多种能力：

通过 <<<>>> 的格式来指定某个主体、图片、视频, 如：<<<element_1>>>、<<<image_1>>>、<<<video_1>>>

长度不能超过 2500 个字符

当 multi_shot 参数为 false 时, 当前参数不得为空

multi_prompt `array`

各分镜信息, 如提示词、时长等

通过 index、prompt、duration 参数定义分镜序号及相应提示词和时长：

最多支持 6 个分镜, 最小支持 1 个分镜
每个分镜相关内容的最大长度不超过 512
每个分镜的时长不大于当前任务的总时长, 不小于 1
所有分镜的时长之和等于当前任务的总时长

用 key:value 承载：

"multi_prompt": [
  {
    "index": int,
    "prompt": "string",
    "duration": "5"
  },
  {
    "index": int,
    "prompt": "string",
    "duration": "5"
  }
]

当 multi_shot 参数为 true 且 shot_type 参数为 customize 时, 当前参数不得为空

image_list `array`

参考图列表

包括主体、场景、风格等参考图片, 也可作为首帧或尾帧生成视频；当作为首帧或尾帧生成视频时：

通过 type 参数来定义图片是否为首尾帧：first_frame 为首帧, end_frame 为尾帧
暂时不支持仅尾帧, 即有尾帧图时必须有首帧图
使用首帧或首尾帧生成视频时, 不能使用视频编辑功能

支持传入图片 Base64 编码或图片 URL（确保可访问）

图片要求：
图片格式支持 .jpg / .jpeg / .png
图片文件大小不能超过 10MB, 图片宽高尺寸不小于 300px, 图片宽高比要在 1:2.5 ~ 2.5:1 之间

参考图片数量与有无参考视频、参考主体数量：
有参考视频时, 参考图片数量和参考主体数量之和不得超过 4
无参考视频时, 参考图片数量和参考主体数量之和不得超过 7
参考图片数量超过 2 时, 不支持设置尾帧

image_url 参数值不得为空

image_url string

图片 URL 或 Base64 数据

type string

图片类型

选项：first_frame, end_frame

element_list `array`

参考主体列表

基于主体库中主体的 ID 配置, 用 key:value 承载：

创建主体请参考：kirin_custom_elements

"element_list": [
  {
    "element_id": long
  },
  {
    "element_id": long
  }
]

参考主体数量与有无参考视频、参考图片数量有关：
如果使用首帧生视频或首尾帧生视频时, 最多支持 3 个主体
有参考视频时, 参考图片数量和参考主体数量之和不得超过 4, 且不支持使用视频角色主体
无参考视频时, 参考图片数量和参考主体数量之和不得超过 7

主体分为视频定制主体（简称：视频角色主体）和图片定制主体（简称：多图主体）, 适用范围不同, 请注意区分

element_id integer

主体库中主体的 ID

video_list `array`

参考视频, 通过 URL 方式获取

可作为特征参考视频, 也可作为待编辑视频, 默认为待编辑视频；可选择性保留视频原声：

通过 refer_type 参数区分参考视频类型：feature 为特征参考视频, base 为待编辑视频
参考视频为待编辑视频时, 不能定义视频首尾帧
通过 keep_original_sound 参数选择是否保留视频原声, yes 为保留, no 为不保留；当前参数对特征参考视频（feature）也生效

有参考视频时, sound 参数值只能为 off

用 key:value 承载：

"video_list": [
  {
    "video_url": "video_url",
    "refer_type": "base",
    "keep_original_sound": "yes"
  }
]

视频要求：
视频格式仅支持 MP4/MOV
视频时长不少于 3 秒, 上限与模型版本有关
视频宽高尺寸需介于 720px（含）和 2160px（含）之间
视频帧率基于 24fps～60fps, 生成视频时会输出为 24fps
至多仅支持上传 1 段视频, 视频大小不超过 200MB

video_url 参数值不得为空

video_url string 必填

视频 URL 地址, 支持 MP4/MOV 格式

refer_type string

参考视频类型

选项：feature, base

默认值：base

keep_original_sound string

是否保留视频原声

选项：yes, no

sound `string`

生成视频时是否同时生成声音

仅 V2.6 及后续版本模型支持当前参数

选项: on, off

默认值: off

mode `string`

生成视频的模式

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

选项: std, pro

默认值: pro

aspect_ratio `string`

生成视频的画面纵横比（宽:高）

未使用首帧参考或视频编辑功能时, 当前参数必填

选项: 16:9, 9:16, 1:1

duration `string`

生成视频时长, 单位 s

使用视频编辑功能（refer_type: base）时, 输出结果与传入视频时长相同, 此时当前参数无效；此时, 按输入视频时长四舍五入取整计量计费

选项: 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15

默认值: 5

watermark_info `array`

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

通过 enabled 参数定义, 用 key:value 承载：

"watermark_info": {
  "enabled": boolean // true 为生成, false 为不生成
}

暂不支持自定义水印

callback_url `string`

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

external_task_id `string`

自定义任务 ID

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

请注意, 单用户下需要保证唯一性

轮询

由于视频生成需要时间, 您需要在创建任务后轮询任务状态

初始响应返回任务 ID 和初始状态. 实际的生成结果必须通过轮询任务状态端点来获取

响应格式

error `object`

错误信息. 仅在状态为 failed 时出现.

code string

错误码

error_message string

详细错误信息

output `array`

生成结果. 仅在状态为 completed 时出现.

content array

生成内容列表

type string

资源类型, 如 video, image

url string

生成内容的 URL

duration number

视频时长

jobId string

远程任务 ID

usage `object`

使用统计. 仅在状态为 completed 时出现.

cost string

总费用 (美元)

discount number

折扣金额

metadata `object`

元数据信息

错误码

错误码	描述
006001094	任务资源不足
006001095	任务响应错误
006001099	任务创建错误

接口提示

认证

authorization string 必填

参数

model string 必填

multi_shot boolean

shot_type string

prompt string

multi_prompt array

image_list array

image_url string

type string

element_list array

element_id integer

video_list array

video_url string 必填

refer_type string

keep_original_sound string

sound string

mode string

aspect_ratio string

duration string

watermark_info array

callback_url string

external_task_id string

轮询

响应格式

error object

code string

error_message string

output array

content array

type string

url string

duration number

jobId string

usage object

cost string

discount number

metadata object

错误码

authorization `string` 必填

model `string` 必填

multi_shot `boolean`

shot_type `string`

prompt `string`

multi_prompt `array`

image_list `array`

image_url `string`

type `string`

element_list `array`

element_id `integer`

video_list `array`

video_url `string` 必填

refer_type `string`

keep_original_sound `string`

sound `string`

mode `string`

aspect_ratio `string`

duration `string`

watermark_info `array`

callback_url `string`

external_task_id `string`

error `object`

code `string`

error_message `string`

output `array`

content `array`

type `string`

url `string`

duration `number`

jobId `string`

usage `object`

cost `string`

discount `number`

metadata `object`