渲染相关接口

提交渲染任务

POST https://api.bestminr.com/api/duomu/render

调用步骤

  1. 确定自己生成视频需要的比例aspect_ratio和分辨率resolution

  2. 从模版列表中根据实际情况,选择与生成视频相对应的场景,记录场景名称name。 根据场景字段resource_typeresource_count,在场景参数中传相应数量和类型的素材。

  3. 根据请求字段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}
  },
  ...
]

如果使用非拼图场景(场景配置信息layoutnull),只能使用一个素材

如果是拼图场景,一个场景内可以使用多个素材,那么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)

文字对齐方式

文字对齐方式取值:leftrightcenter

文本框背景颜色

每个文字都有一个文本框,目前可以指定文本框颜色,相当于指定文字背景颜色。

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默认为视频时长,如果超出音频时长则为音频时长。

获取渲染任务进度

获取渲染任务进度有两种方式,一种是使用平台回调机制,另一种是直接轮训调用获取视频信息接口

推荐使用系统的推送服务,需要提前配置回调地址