视频合成接口必读

1.生产环境地址

• 生产环境接口地址: https://openman.weta365.com/metaman/open/需要调用的接口地址
• 更多接口样例:接口样例点这里

2.重要提示

• 所有生成的素材或结果视频，仅保证留存30天，30天后数据会被清理，请及时留存
• 视频合成时长扣减逻辑为1:1,即生成10秒的视频，扣减10秒的合成时长

3.权限校验(默认针对所有接口)

• 接口请求头添加：appKey 开放平台申请的appKey；
• 接口请求头添加：timestamp 系统时间的秒数；
• 接口请求头添加：signature 根据appKey和timestamp加密生成的签名,5分钟过期(授权码，通过“appkey+secret+timestamp”进行md5加密，得到的32位MD5值。每次请求实时计算签名，签名有效期为10分钟。（加号参与字符串拼接）)。
• appkey和signature及加密算法视频合成,附录一

4.视频合成接口介绍

总体有avatar、video、tag、subtitles、back_audio、audio、text共7种素材,实际包含8种(video类型可传图片和视频素材)，各种素材间可以自由组合，但有特定的规则限制。

5.contentType素材类型说明

• avatar类型：数字人类型
• video类型： 多媒体素材类型，可传输视频或图片的地址
• tag类型： 标题类型
• subtitles类型： 字幕类型，只有在text类型时，该类型才生效，且字幕属性的设置，在一个item中设置，全局生效，多次设置，后一个的设置会覆盖掉之前的设置
• back_audio类型： 背景音频
• audio类型： 和text类型互斥，该类型下，不可传字幕类型
• text类型：文本类型，于audio类型互斥，该类型下可传subtitles类型设置

6.公共参数说明

• x:素材左侧到背景框左侧的距离，单位像素
• y:素材顶部到背景框顶部的距离，单位像素
• width:素材的宽，单位像素
• height:素材的高，单位像素
• contentType： 素材的7种类型
• content：根据素材类型做相应填充
• wetaSpeakerId： 查询数字人时，查到的主键id
• magicSpeakerId： 选择配音的主键，例如：moqianxue_meet_24k
• startTime：开始时间,默认0
• stopTime：结束时间,默认该台词的结束时间,不可超过音频的时长
• fontname：字体名称,查询字体时的key
• bold:1加粗,默认0
• fontsize:字体大小，建议15
• primaryColour：字体颜色，格式类似如下：#RRGGBB（#开头，顺序为RGB） ，可参考链接：
  RGB参考地址 ,取值例如：#FFFF00
• underline：1有下划线,默认0
• italic： 1斜体,默认0
• items：列表数据，每一个item代表一页视频的合成
• detailList：列表数据，每一个detail代表一个素材的设置

注意：

1. 如果是前端调用，需要将long类型数字，转换成字符串发送，否则容易精度丢失，导致任务数据异常
2. 音频、视频和图片素材的链接，建议使用类似".mp4,.png,.wav"等结尾

7.时间参数的特别说明

• detailList集合的子项视为一个item
• 在每一个item中，时间的起点是0ms,终点是相应的音频的时长（或者文本转成音频后的相应的音频的时长）
• startTime控制着素材出现的时机，startTime大于等于0，小于stopTime。
• stopTime控制着素材消失的时机，stopTime大于startTime，不可大于item的整体时长。
• video类型可以不设置startTime和stopTime，系统会自动填充，分别默认为0和item的时长

8.各类型参数说明

类型	参数	必传	参数说明	样例
avatar	contentType	是	数字人类型必传，(时长默认是（text）文本转语音的时长或(audio的时长))	avatar
	sortNum	是	层级1-100	1
	x	是	素材左侧到背景框左侧的距离，单位像素	400
	y	是	素材顶部到背景框顶部的距离，单位像素	300
	wetaSpeakerId	是	查询数字人时，查到的主键	1644252493837897728
	width	否	素材的宽，单位像素（宽高等比例缩放）	1080
	height	否	素材的高，单位像素（宽高等比例缩放）	1920
	useAvatarHead	否	默认false，需要合成头像时传true	false
	headx	否	查询数字人时查到的headx	400
	headr	否	查询数字人时查到的headr	400
	heady	否	查询数字人时查到的heady	252
video	contentType	否	视频或图片类型	video
	sortNum	否	层级1-100	1
	x	是	素材左侧到背景框左侧的距离，单位像素	400
	y	是	素材顶部到背景框顶部的距离，单位像素	300
	content	是	视频或图片的地址，建议视频或图片宽高不大于1920	https://mobvoi-digitalhuman-public.weta365.com/itm/1647067732312723456_641600_1234.png
	width	否	素材的宽，单位像素	400
	height	否	素材的高，单位像素	800
	startTime	否	开始时间,ms	0
	stopTime	否	结束时间,ms	850
	loop	否	是否需要循环播放	false
tag	contentType	否	标题类型
	sortNum	是	层级1-100	10
	content	是	标题内容，文字	我的视频
	x	是	素材左侧到背景框左侧的距离，单位像素	400
	y	是	素材顶部到背景框顶部的距离，单位像素	300
	startTime	是	开始时间,ms	0
	stopTime	是	结束时间,ms	850
	fontname	否	字体名称	STSong
	fontsize	否	字体大小	60
	primaryColour	否	#RRGGBB（#开头，顺序为RGB）,参考:RGB参考地址	#000000
subtitles	contentType	否	字幕类型，当且仅当text类型存在时，可传该类型（时长默认是（text）文本转语音的时长）	subtitles
	fontname	否	字体名称	STSong
	bold	否	1加粗,默认0	0
	subtitleUsepx	否	使用像素控制，固定值 Y	Y
	fontsize	否	字体大小	19
	primaryColour	否	#RRGGBB（#开头，顺序为RGB）,参考附录，或百度RGB	#RRGGBB（#开头，顺序为RGB）
	underline	否	1有下划线,默认0	0
	italic	否	1斜体,默认0	0
	bottomSpace	否	字幕底部间距，像素	2
	wordSpace	否	字幕字间距，单位像素	3
back_audio	contentType	否	背景音频类型	back_audio
	content	是	背景音频地址，时长不小于1秒	https://mobvoi-digitalhuman-public.cn-bj.ufileos.com/metaman/storage_audio/DEFAULT_GROUP/20221022/10b325d8ce7243d0ac0a1face48bf926.8c738421dfa4423cb84b97db112d257f.5054e55205.wav
	startTime	否	开始时间,ms	0
	stopTime	否	结束时间,ms	850
	volume	否	音量大小，默认1.0，小于则声音变小，浮点数，保留小数点后一位，最大值1.0	1.0
audio	contentType	否	驱动数字人音频地址，与text类型互斥，且两者必传其一	audio
	content	是	驱动数字人的音频地址(建议使用魔音接口生成音频)	https://mobvoi-speech-public.mobvoi.com/mobvoi-tts/voice-maker/synthesis_audio/26526559/1681838639099/f2c1911010e5b54a0f10f6da6672affe.wav
	volume	否	音量大小，默认1.0，小于则声音变小，浮点数，保留小数点后一位	1.0
text	contentType	否	驱动数字人文字内容，与audio类型互斥，且两者必传其一	text
	content	是	文字	奇妙元测试生成数字人，调用魔音接口，生成语音,长度不能超过2000
	magicSpeakerId	是	声音的id,可以在开放平台声音库中下载发音人列表（ https://openapi.mobvoi.com/pages/sound-library ）	moqianxue_meet_24k
	audioType	否	合成音频的格式,默认值wav,暂不支持其他格式	wav
	convert	否	是否转化为机器声,可选值：robot，传其他字符，则使用默认值
	mergeSymbol	否	粗粒度合成参数，默认为false,可以指定为true，打开后语气停顿会更加接近真人效果
	pitch	否	语调参数，参数小于0则语调变低，反之则高，默认值：0，可选值：-10<pitch<10，超出可选值，则使用默认值
	rate	否	音频采样率：8000/16000/24000,默认值：16000，超出可选值，则使用默认值
	speed	否	发音人合成的语速，支持小数点后一位,可选值:0.5-2.0,默认值：1.0，超出可选值，则使用默认值
	volume	否	合成音量：默认值：1.0，可选值：0.1-1.0，超出可选值，则使用默认值

json样例(接口样例点这里)：

{
            "callbackUrl": "",
            "height": 1920,
            "name": "测试1",
            "width": 1080,
            "items": [
                {
                    "detailList": [
                        {
                            "contentType": "avatar",
                            "wetaSpeakerId": "1644252497877012480",
                            "sortNum": 2,
                            "x": 0,
                            "y": 0
                        },
                        {
                            "content": "今天天气不错！",
                            "contentType": "text",
                            "magicSpeakerId": "moqianxue_meet_24k"
                        }

                    ]
                }
            ]
        }

9.结果回调接口

下发合成json时，存在非必传字段callbackUrl，当此字段有值时，合成结束(成功/失败)后触发回调，回调的数据结构和《视频合成_结果查询》的数据结构一致。详细说明如下：

• 回调接口说明

  回调接口为post接口，回调数据在请求体内,java代码的样例如下：

      @PostMapping("/test/callback")
      public R receiveResult(@RequestBody Object obj) {
          log.info("合成回调结果={}", JSONObject.toJSONString(obj));
          // 返回结果可自定义，暂不关注
          return R.success();
      }
  

  回调json样例：

  	{
          "taskId": "1681232680777289728",
          "height": 1920,
          "width": 1080,
          "coverUrl": "https://mobvoi-digitalhuman-public.cn-bj.ufileos.com/60577785cover.png",
          "resultUrl": "https://mobvoi-digitalhuman-public.cn-bj.ufileos.com/60577785video.mp4",
          "name": "测试",
          "status": "suc",
          "statusDesc": "成功",
          "duration": "8320",
          "created": "2023-07-18 17:21:21",
          "lastUpdateTime": "2023-07-18 17:21:44"
      }
  

10.返回值说明

code：为200时，表示操作成功，其他数字表示失败；
message：失败原因
data：返回数据
{ "code": 200, "message": "操作成功", "data": {} }

状态码	含义
200	接口调用成功
401	权限校验不通过
-1	接口参数校验不通过

11.附录一

1. 开放平台注册应用，注册地址： https://openapi.mobvoi.com/index

   登陆注册-->点击头像，选择‘我的应用’-->创建应用-->查看详情，获取AppKey和AppSecret

   注意：新创建的应用没有合成时长，在直播间合成时会被拒绝掉

2. 获取签名算法：java 代码示例

       public static void main(String[] args) throws Exception{
           String appkey = "你的appkey";
           String secret = "你的secret";
           long current = System.currentTimeMillis();
           String timestamp = String.valueOf(current / 1000);
           String signature = md5(appkey, secret, timestamp);
           System.out.println("timestamp="+timestamp);
           System.out.println("signature="+signature);
       }
   
       private static String md5(String appkey, String secret, String timestamp) {
           String plainText = String.join("+", appkey, secret, timestamp);
           byte[] secretBytes = null;
           try {
               secretBytes = MessageDigest.getInstance("md5").digest(plainText.getBytes());
           } catch (NoSuchAlgorithmException e) {
               throw new RuntimeException("not found the md5");
           }
           String md5code = new BigInteger(1, secretBytes).toString(16);
           for (int i = 0; i < 32 - md5code.length(); i++) {
               md5code = "0" + md5code;
           }
           return md5code;
       }