视频合成
视频合成服务是基于模板变量替换的服务，区别于普通的视频创作API，基于模板变量的合成服务可通过简单的模板合成API接入即可实现复杂内容定义的模板生成，无需理解视频元素布局、内容定义等，适用于剪同款、一键替换等场景下的视频合成服务。同时智云的MGC合成渲染引擎提供serverless能力，高并发任务下依旧能保障合成效率。
前提准备
标题部分 前提准备1. 域名及请求加签
标题部分 1. 域名及请求加签域名说明
模板基本概念
标题部分 模板基本概念模板
标题部分 模板用于自动化合成的包含多组排列有序的元素集合的标准化数据结构，模板通过卡片组装而成。模板定义了一个视频中的每个画面元素，这些元素有些可以通过外部输入进行替换，有些则是使用模板创建之初所用的素材。
卡片
标题部分 卡片一个模版当中会有很多的卡片，由多个有序的卡片组合而成。其中的每个卡片都会有很多的变量素材组成。卡片概念是针对一组有共性、通用的一组素材(视频、图片等)而组成的一个抽象概念。
模板合成
标题部分 模板合成1. 获取变量模板列表
标题部分 1. 获取变量模板列表HTTP协议
标题部分 HTTP协议- 请求path：/external/template/authorize/query?pageNo=1&pageSize=10&query=模板
- 请求类型：GET
入参字段说明
标题部分 入参字段说明| 字段 | 是否必填 | 类型 | 说明 |
|---|---|---|---|
| query | 否 | String | 搜索信息, 搜索模板标题或模板 id |
| pageNo | 是 | Integer | 当前页数 |
| pageSize | 是 | Integer | 页面大小 |
返回结果说明
标题部分 返回结果说明| 字段 | 类型 | 说明 |
|---|---|---|
| templateId | String | 模板 Id |
| name | String | 模板名称 |
| preview | Object | 模板预览信息 |
| gmtCreate | Long | 创建时间 |
| gmtModify | Long | 修改时间 |
preview结构：
| 字段 | 类型 | 说明 |
|---|---|---|
| previewImg | String | 模板预览封面 |
| previewVideo | String | 模板预览视频 |
- 返回样例
{
"records": [
{
"templateId": "a689f48205f1458da3c8cc1679c98076",
"name": "转存验证2",
"gmtCreate": 1663566348110,
"gmtModify": 1663566475672,
"preview": {
"previewImg": "http://xhzy-test.oss-cn-hangzhou.aliyuncs.com/jimu_upload/TEST/2022-09-19/%E9%AB%98%E5%85%B4_v64e1.gif",
"previewVideo": "http://xhzy-test.oss-cn-hangzhou.aliyuncs.com/jimu_upload/TEST/2022-09-19/%E9%AB%98%E5%85%B4_v64e1.gif"
}
}
],
"total": "1",
"size": "12",
"current": "1",
"pageSize": "12",
"pageNo": "1",
"pages": "1",
"searchCount": true
}2. 获取模板变量列表
标题部分 2. 获取模板变量列表HTTP协议
标题部分 HTTP协议- 请求path：/external/template/get_variables/{templateId}
- 请求类型：GET
入参字段说明
标题部分 入参字段说明| 字段 | 是否必填 | 类型 | 说明 |
|---|---|---|---|
| templateId | 是 | String | 模板 ID |
返回结果说明
标题部分 返回结果说明| 字段 | 类型 | 说明 |
|---|---|---|
| unitKey | String | 卡片 key, 卡片的唯一标识 |
| variables | List<Object> | 卡片变量, 每张卡片上的入参变量 |
variables结构：
| 字段 | 类型 | 说明 |
|---|---|---|
| key | String | 变量 key, 卡片上变量的唯一标识 |
| type | String | 变量类型, 标明使用该变量的组件类型 |
| name | String | 变量描述, 说明该变量需要使用什么数据作为入参 |
| dataFormat | Object | 可视化组件变量描述 当组件为可视化组件类型时, 对该组件入参格式的说明,不同组件的数据格式也会不同, 可能是数组或对象等 例如下面的样例, 折线图组件需要数组数据, 公司简介需要对象数据 |
| extInfo | Object | 其他变量信息, 在做 数字人和声音 替换时, 传入对应值 |
type枚举值：
| 枚举类型 | 说明 | |
|---|---|---|
| video | 视频组件 | |
| image | 图片组件 | |
| audio | 音频组件 | |
| subtitle | 字幕组件 | |
| tts | 语音组件 | |
| vizz | 可视化组件 | |
| virtual_host | 虚拟主播组件 |
- 返回样例
[
{
"unitKey": "xxx",
"variables": [
{
"key": "yyy",
"type": "tts",
"name": "变量描述1",
"extInfo": {
"per": "请填入发音人编号"
}
},
{
"key": "zzz",
"type": "vizz_old",
"name": "折线图变量",
"dataFormat": [
{
"x": "文字1", // x 轴坐标值
"y": 76 // y 轴坐标值
},
{
"x": "文字2", // x 轴坐标值
"y": 88 // y 轴坐标值
},
{
"x": "文字3", // x 轴坐标值
"y": 164 // y 轴坐标值
}
]
},
{
"key": "uuu",
"type": "vizz_old",
"name": "公司简介组件变量",
"dataFormat": {
"id": "601288", // 公司代码
"name": "农业银行", // 公司名称
"date": "2010-07-15" // 公司上市时间
}
}
]
}
]3. 视频合成接口
标题部分 3. 视频合成接口HTTP协议
标题部分 HTTP协议- 请求path：/external/template/produce
- 请求类型：POST
入参字段说明
标题部分 入参字段说明| 字段 | 是否必填 | 类型 | 说明 |
|---|---|---|---|
| templateId | 是 | String | 模板 ID |
| callbackUrl | 否 | String | 回调接口地址, 合成完成后, 自动回调接口发送结果 |
| templateVariables | 否 | List<Object> | 根据第一步获得的数据结构, 填入模板变量入参 |
templateVariables结构：
| 字段 | 是否必填 | 类型 | 说明 |
|---|---|---|---|
| unitKey | 是 | String | 卡片 key, 卡片的唯一标识 |
| variables | 是 | List<Object> | 卡片变量, 每张卡片上的入参变量 |
variables结构：
| 字段 | 是否必填 | 类型 | 说明 |
|---|---|---|---|
| key | 是 | String | 变量 key, 卡片上变量的唯一标识 |
| value | 是 | Object | 变量值 卡片变量的入参值 - video、image、audio，value值即为素材对象，MediaObject类型 - subtitle，value值即为文本内容，String类型 - tts，value值即为文本内容，String类型 - vizz，value值即为Data数据内容，Object 类型 - virtual_host，value值即为文本内容，String类型 |
| extInfo | Object | 其他变量信息, 在做 数字人和声音 替换时, 传入对应值 | |
| replaceType | String | 元素替换类型 替换策略 移除元素 - removeVariable 移除卡片 - removeCard 兼容显示当前素材 - undo 模板不合成 - removeAll |
extInfo结构：
| 字段 | 是否必填 | 类型 | 说明 |
|---|---|---|---|
| avatar | 否 | String | 数字人形象, 虚拟主播形象衣服中的代码 |
| per | 否 | String | 发音人, 声音代码 |
replaceType枚举值：
| 枚举类型 | 说明 | |
|---|---|---|
| removeVariable | 移除元素 | |
| removeCard | 移除卡片 | |
| undo | 兼容显示当前素材 | |
| removeAll | 模板不合成 |
- 请求示例
{
"templateId": "986de72cb8f74d4695a201a1fe61a31a",
"templateVariables": [
{
"unitKey": "xxx",
"variables": [
{
"key": "yyy",
"value": "变量填充1"
},
{
"key": "uuu",
"value": {
"id": "601288", // 公司代码
"name": "农业银行", // 公司名称
"date": "2010-07-15" // 公司上市时间
}
}
]
}
]
}返回结果说明
标题部分 返回结果说明| 字段 | 类型 | 说明 |
|---|---|---|
| data | String | 合成的视频 id, 建议业务方打印返回的任务id，用于合成链路排查使用 |
- 返回样例
{
"success":true,
"code":"",
"message":"",
"requestId":"18b4932f5e1b8695",
"data":"2dd965de203545d5ad53af26d615ded2"
}4. 获取任务结果
标题部分 4. 获取任务结果HTTP协议
标题部分 HTTP协议- 请求path：/external/play_job/detail/{jobId}
- 请求类型：GET
入参字段说明
标题部分 入参字段说明| 字段 | 是否必填 | 类型 | 说明 |
|---|---|---|---|
| jobId | 是 | String | 视频 id |
返回结果说明
标题部分 返回结果说明| 字段 | 类型 | 说明 |
|---|---|---|
| jobId | String | 视频 ID |
| jobType | Integer | 视频类型, 任务执行类型: 0 - 单视频任务;1 - 批量视频任务 |
| bizId | String | 业务标示ID, 业务自定义标示, jobType 为 0 时, bizId 是模板 ID jobType 为 1 时, bizId 是任务 ID |
| playTitle | String | 合成视频名称, 默认使用模板名称作为视频名称 |
| dictParam | Object | 数据字典, 批量任务使用, 合成视频时, 使用到的数据入参 |
| dataTime | String | 数据时间, 批量任务使用, 合成视频时的数据时间 |
| batchNo | String | 批次号, 批量任务使用, 视频对应的任务批次号 |
| jobStatus | Integer | 视频状态 |
| jobResult | Object | 合成结果 |
| synthStarted | Long | 合成发起时间, 发起智能模板合成请求的时间 |
| synthUpdated | Long | 合成完成时间, 接收到智能模板合成结果的时间 |
| triggerUserId | String | 触发用户id, 触发合成的用户 id |
| belongUserId | String | 归属用户id, 模板的用户 id |
| tenantId | String | 机构id, 模板的机构 id |
jobStatus枚举值：
| 枚举类型 | 说明 | |
|---|---|---|
| 0 | 作业初始化 | |
| 1 | 构建成功 | |
| 11 | 构建失败 | |
| 2 | 协议转换成功 | |
| 21 | 协议转换失败 | |
| 3 | 发起合成任务 | |
| 4 | 合成任务成功 | |
| 41 | 合成任务失败 |
jobResult结构：
| 字段 | 类型 | 说明 |
|---|---|---|
| requestId | String | 合成请求 ID |
| taskStatus | String | 合成任务状态 |
| message | String | 合成消息 |
| duration | Double | 视频时长 |
| coverUrl | Object | 视频封面 |
| url | String | 视频链接 |
- 返回样例
{
"success":true,
"code":"",
"message":"",
"requestId":"631066fd96d317d506cd3ab1250adb74",
"data":{
"id":"497",
"status":0,
"gmtCreate":1662014052000,
"gmtModified":1662014057000,
"deleted":0,
"jobId":"2dd965de203545d5ad53af26d615ded2",
"jobType":0,
"bizId":"986de72cb8f74d4695a201a1fe61a31a",
"playTitle":"转存封面验证",
"jobStatus":4,
"synthStarted":1662014052000,
"synthUpdated":1662014057000,
"jobResult":{
"coverUrl":{
"default":"https://***/4b4f4c2cc512431483d7b4fcdbc74c21_default.png"
},
"duration":3.019,
"requestId":"jimu_2dd965de203545d5ad53af26d615ded2",
"taskStatus":"mgcFinish",
"url":"http://***/4b4f4c2cc512431483d7b4fcdbc74c21.mp4"
},
"triggerUserId":"236422856946230278",
"belongUserId":"236422856946230278",
"tenantId":"132066159006606348"
}
}5. 任务结果回调接口(客户提供)
标题部分 5. 任务结果回调接口(客户提供)客户需按下述规范提供回调接口
HTTP协议
标题部分 HTTP协议- 请求path：(客户提供)
- 请求类型：POST
入参字段说明
标题部分 入参字段说明Query 入参
| 字段 | 是否必填 | 类型 | 说明 |
|---|---|---|---|
| timestamp | 是 | String | 时间戳, 接口调用时的时间戳 |
| signature | 是 | String | 加签信息, 加签信息计算规则 md5(sk + $ + timestamp + $ + ak) timestamp 就是上面的入参 aksk 与向客户提供的 aksk 相同 为保证接口请求安全, 客户需验证接收到的加签信息是否一致 |
Body 入参
| 字段 | 是否必填 | 类型 | 说明 |
|---|---|---|---|
| jobId | 是 | String | 视频 ID |
| jobType | 否 | Integer | 视频类型, 任务执行类型: 0 - 单视频任务;1 - 批量视频任务 |
| bizId | 否 | String | 业务标示ID, 业务自定义标示, jobType 为 0 时, bizId 是模板 ID jobType 为 1 时, bizId 是任务 ID |
| playTitle | 否 | String | 合成视频名称, 默认使用模板名称作为视频名称 |
| dictParam | 否 | Object | 数据字典, 批量任务使用, 合成视频时, 使用到的数据入参 |
| dataTime | 否 | String | 数据时间, 批量任务使用, 合成视频时的数据时间 |
| batchNo | 否 | String | 批次号, 批量任务使用, 视频对应的任务批次号 |
| jobStatus | 否 | Integer | 视频状态 |
| jobResult | 是 | Object | 合成结果 |
| synthStarted | 否 | Long | 合成发起时间, 发起智能模板合成请求的时间 |
| synthUpdated | 否 | Long | 合成完成时间, 接收到智能模板合成结果的时间 |
| triggerUserId | 否 | String | 触发用户id, 触发合成的用户 id |
| belongUserId | 否 | String | 归属用户id, 模板的用户 id |
| tenantId | 否 | String | 机构id, 模板的机构 id |
- 请求示例
{
"id":"497",
"status":0,
"gmtCreate":1662014052000,
"gmtModified":1662014057000,
"deleted":0,
"jobId":"2dd965de203545d5ad53af26d615ded2",
"jobType":0,
"bizId":"986de72cb8f74d4695a201a1fe61a31a",
"playTitle":"转存封面验证",
"jobStatus":4,
"synthStarted":1662014052000,
"synthUpdated":1662014057000,
"jobResult":{
"coverUrl":{
"default":"https://***/4b4f4c2cc512431483d7b4fcdbc74c21_default.png"
},
"duration":3.019,
"requestId":"jimu_2dd965de203545d5ad53af26d615ded2",
"taskStatus":"mgcFinish",
"url":"http://***/4b4f4c2cc512431483d7b4fcdbc74c21.mp4"
},
"triggerUserId":"236422856946230278",
"belongUserId":"236422856946230278",
"tenantId":"132066159006606348"
}返回结果说明
标题部分 返回结果说明| 字段 | 类型 | 说明 |
|---|---|---|
| success | Boolean | 是否调用成功, 返回接口是否调用成功的标识 |
- 返回样例
{
"success":true
}6. 常见错误码
标题部分 6. 常见错误码失败code码：
| 错误码 | 说明 |
|---|---|
| SW-JM-1000 | 系统异常, 请联系管理员 |
| SW-JM-1001 | 参数错误 |
| SW-JM-1002 | 用户账号异常 |
| SW-JM-2001 | 模板操作异常 |