渲染相关接口
提交渲染任务
POST https://api.bestminr.com/api/duomu/render
调用步骤
确定自己生成视频需要的比例
aspect_ratio
和分辨率resolution
。从模版列表中根据实际情况,选择与生成视频相对应的场景,记录场景名称
name
。 根据场景字段resource_type
、resource_count
,在场景参数中传相应数量和类型的素材。根据请求字段Request Body中的要求,完善请求数据以后,就可以使用数据请求生成视频接口,等待视频制作完成。
请求参数
Query Parameters
参数名 | 类型 | 是否必须 | 说明 |
---|---|---|---|
access_token | String | 是 | 请求接口所需凭证 |
Request Headers
"Content-Type": "application/json"
Request Body
参数名 | 类型 | 是否必须 | 说明 |
---|---|---|---|
theme_id | String | 否 | 模板id,此处可以不传,在场景参数里指定 |
aspect_ratio | String | 是 | 生成视频的比例,支持的比例有 1/1、3/4,16/9,9/16,必须和使用的模板场景一致 |
resolution | String | 否 | 生成视频的分辨率,支持 360p、480p、720p、1080p,默认生成 360p |
sections | 场景 | 是 | 每个视频由多个Section组成,每个都有对应的素材文件和配文 |
audio | 音乐 | 否 | 生成视频时使用的背景音乐,如果没有字段信息,但是提供了 theme_id,会使用模版默认音乐 |
dubbings | 配音 | 否 | 视频的配音音轨 |
详细参数解释见渲染参数说明
调用示例
curl --request POST \
--url "https://api.bestminr.com/api/duomu/render?access_token=<access_token>"
--header 'Content-Type: application/json'
--data <request_body>
返回数据
{
"status": "", // 制作状态
"messages": [], // 如果 status 为 error,会有相应的报错信息
"video_id": "", // video_id 用来反查视频信息
"video_url": "" // 如果 status 为 success,url 为视频内容
}
错误码
HTTP Status Code 400
{
"http_status_code": 400,
"messages": [
{
"code": 20006, // 素材处理出错
"url": "<url>",
"msg": "Footage <url> process error"
},
{
"code": 20008, // 请求素材出错
"url": "<url>",
"msg": "Request footage <url> error"
},
{
"code": 20009, // 素材 url 格式错误
"msg": "Footage sections.0.footages.0.url url format error",
"field_key": "sections.0.footages.0.url"
},
{
"code": 20013, // 素材上传出错
"url": "<url>",
"msg": "Upload footage <url> error"
},
{
"code": 20014, // 无法使用该素材
"url": "<url>",
"msg": "Cant find resource when use <url>"
},
{
"code": 21005, // 素材类型与场景所需素材类型不匹配
"scene_name": "<scene_name>",
"resource_type": "<resource_type>",
"msg": "Scene <scene_name> need resource type <resource_type>"
},
{
"code": 21006, // 服务器渲染错误,请联系客服
"msg": "Render server error, please connect service"
},
{
"code": 21007, // 渲染已经被手动停止
"msg": "Render is stopped"
},
{
"code": 30001, // 场景时长不能为空值
"msg": "Section duration cant be null"
}
{
"code": 30002, // 素材类型不支持
"url": "<url>",
"msg": "Content type <content_type> is unsupport"
},
{
"code": 30005, // 无效的 theme_id
"msg": "Please check theme id"
},
{
"code": 30003, // 使用场景名称有误
"scene_name": "<scene_name>",
"msg": "Cant find scene name <scene_name>"
},
{
"code": 30006, // 素材数 footage_count 不满足场景所需素材数 resource_count
"footage_count": "<footage_count>",
"resource_count": "<resource_count>",
"msg": "Footages is not enough for this scene"
},
{
"code": 30007, // 模版不可用
"msg": "Theme is Invalid"
},
{
"code": 31003, // 请选择场景名称
"msg": "Please choose scene name for this section"
},
{
"code": 31004, // 素材 url 不为空
"msg": "Footage sections.0.footages.0.url url is missing",
"field_key": "sections.0.footages.0.url"
},
{
"code": 31005, // sections 不能为空
"msg": "Please input sections"
},
]
}
渲染参数说明
渲染参数结构如下:
参数结构
{
"theme_id": "xxx", // 选择的模版id
"resolution": "480p", // 生成视频的分辨率,支持 360p、480p、720p、1080p,默认生成 360p
"aspect_ratio": "3/4", // 生成视频的比例,支持的比例有 1/1、3/4,16/9,9/16,必须和使用的模板场景一致
/* 场景参数*/
"sections": [
{ /* 每个场景的参数 */ },
...
],
/* 音乐参数*/
"audio": {
"url": "https://example.com/xxx.mp3"
},
/* 配音参数 */
"dubbings": {
"url": "https://example.com/xxx.mp3"
},
}
- 场景参数:每个视频由多个Section组成,每个都有对应的素材文件和配文
- 音乐参数:生成视频时使用的背景音乐,如果没有字段信息,但是提供了 theme_id,会使用模版默认音乐
- 配音参数:视频的配音音轨
场景参数
场景参数sections
如下:
[
{
"scene_name": "giD_5_1", // 必须,场景名称,格式:模板id_模板场景名称
"duration": 150, // 可选,场景时长,单位:帧,每秒25帧,不传默认取该场景的推荐时长
"footage_fit": "auto", // 可选,素材尺寸适配选项,默认为 auto
"bg_color": "rgba(255, 255, 255)", // 可选,场景背景色,不支持透明度修改,默认为该场景配置背景色
/* 场景素材参数 */
"footages": [
{
"url": "https://cdn.static.bestminr.com/theme_test/1.jpg"
}
],
/* 场景配文参数 */
"texts": {
"title": { /* 文字通用参数 */ }, // 主标题
"subtitle": { /* 文字通用参数 */ }, // 副标题
}
},
...
]
scene_name
需要从模板信息里获取
footage_fit
素材尺寸适配选项
fill
:填充,素自动缩放素材大小,充满显示区域(显示区域取决于模板效果,大部分情况是充满全屏)contain
:自适应,素材自身大小比例不变,自适应于显示区域,素材未覆盖的部分为场景背景色auto
:自动,全屏类场景中,如果素材比例和显示区域都为横版,素材填充,如果素材比例为竖版,显示区域为横版,素材自适应;拼图场景和部分图文场景,素材填充显示
场景素材参数
场景素材参数footages
如下:
[
{
"url": "https://example.com/xx.jpg", // 必须,图片素材或视频素材的 URL
"beginning": 0, // 可选,视频素材截选参数,从第几帧开始裁剪视频素材,单位为帧,默认为0
"length": 50, // 可选,视频素材截选参数,需要裁剪视频素材多少帧,每秒25帧,单位为帧
"loop": false, // 可选,如果值为 true,视频素材截取时长小于场景时长,视频素材会在该场景中循环播放
"vol_improve_fgm": 100, // 可选,视频素材同期声音量调整,取值范围 0-200,默认为 100
"vol_improve_bgm": 100, // 可选,渲染到该视频素材时,背景音乐音量调整,取值范围 0-200,默认为 100
"crop": "1920x1080+2+4", // 可选,素材的裁剪参数,格式:{width}x{height}+{x}+{y}
},
...
]
如果使用非拼图场景(场景配置信息中 layout
为 null
),只能使用一个素材
如果是拼图场景,一个场景内可以使用多个素材,那么footages
数组可以传入多个素材对象。
素材裁剪参数
crop
参数格式为{width}x{height}+{x}+{y}
,单位为像素,素材左上角为原点
crop
表示以(x, y)
点为裁剪起始点,裁剪宽度{width}
,裁剪高度{height}
,最后得到一个宽度为width
、高度为height
的新素材。
视频素材截选参数
如果素材是视频,length
参数默认为场景时长duration
,如果视频素材总帧数小于场景时长duration
, 导出的视频中,该场景则视频素材会播放到最后一帧后停在最后一帧。
截取视频素材时,beginning + length
必须小于视频素材总帧数。
每秒25帧
文字通用参数
文字通用参数如下:
{
"content": "请输入文字", // 必须,配文文字内容
"font_family": "思源黑体 Heavy", // 可选,文字使用的字体,默认使用模板内置配置
"font_size": 16, // 可选,文字大小,默认使用模板内置配置
"color": "rgba(1, 1, 1, 1)", // 可选,字体颜色,默认使用模板内置配置
"bg_color": "rgba(255, 255, 255, 1)", // 可选,文本框背景颜色,默认使用模板内置配置
"text_shadow": "0.05em 0.05em 0.15em rgba(0, 0, 0, 0.8)", // 可选,文字阴影,默认使用模板内置配置
"x": 0.49689, // 可选,文字 x 坐标,不推荐使用,默认使用模板配置
"y": 0.833705, // 可选,文字 y 坐标,不推荐使用,默认使用模板配置
"text_align": "center", // 可选,文字对齐方式,默认使用模板配置
}
文字字体
font_family
文字字体,可以从获取字体列表接口获取目前系统内置的字体
文字颜色
color
字体颜色取值类型:rgba(R, G, B, opacity)
,例如:rgba(255, 255, 255, 0.98)
文字阴影
text_shadow
文字阴影取值:h-shadow v-shadow blur rgba(R, G, B, opacity)
,例如:0.05em 0.05em 0.15em rgba(0, 0, 0, 0.8)
h-shadow
为水平阴影的位置,允许负值。
v-shadow
为垂直阴影的位置。允许负值。
blur
为模糊的距离。
R,G,B
取值范围0-255
整数,opacity
取值范围0-1
的浮点数,例如:rgab(255, 255, 255, 0.98)
文字对齐方式
文字对齐方式取值:left
,right
,center
文本框背景颜色
每个文字都有一个文本框,目前可以指定文本框颜色,相当于指定文字背景颜色。
bg_color
参数格式和文字颜色一致。
文字位置
文字坐标原点(0, 0)
为画面左上角,不推荐直接指定x
y
数值,可能会有误差,默认会用模板配置。
音乐参数
音乐参数audio
一般用于视频背景音乐
{
"url": "https://example.com/xxx.mp3", // 必须,音频文件的 URL
"start": 0.1, // 可选,音频在视频中开始播放的时间点,单位为秒,默认为0
"beginning": 1.2, // 可选,从这个时间点开始截选该音频,单位为秒,默认为0
"length": 23.1, // 可选,总共截选该音频的时长,单位为秒
"vol_improve": 100, // 可选,音频音量调整,范围 0-200,默认为 100
}
说明:
length
默认为视频时长,如果超出音频时长则为音频时长vol_improve
一般用于校正音乐音量,避免出现音乐声音过大或者过小的情况audio
字段如果不传,音频为模板内置的默认音乐
配音参数
配音参数dubbings
和音乐参数类似,一般用于视频旁白
{
"url": "https://example.com/xxx.mp3", // 必须,配音文件的 URL
"start": 0.1, // 可选,配音在视频中开始播放的时间点,单位为秒,默认为0
"beginning": 1.2, // 可选,从这个时间点开始截选该音频,单位为秒,默认为0
"length": 23.1, // 可选,总共截选该音频的时长,单位为秒
"vol_improve": 100, // 可选,音频音量调整,范围 0-200,默认为 100
}
length
默认为视频时长,如果超出音频时长则为音频时长。
获取渲染任务进度
获取渲染任务进度有两种方式,一种是使用平台回调机制,另一种是直接轮训调用获取视频信息接口。
推荐使用系统的推送服务,需要提前配置回调地址。