3D数字人视频合成接入指南

重要

本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。

3D数字人视频合成服务为您提供输入文本以及输入音频合成为3D虚拟数字人指定格式的视频,并且通过返回的视频链接下载视频内容。

功能介绍

  • 形象配置

    • 支持选择不同3D数字人形象,并进行装扮。具体可参考:配置数字人形象

    • 支持通过参数指定本次视频合成需要使用的3D数字人形象,具体数字人形象列表可以从平台3D资产中心获取(获取3D数字人形象code

  • 数字人驱动

    • 支持数字人表情、口型、动作驱动

  • 视频编码信息

    • 编码格式: h264

    • 帧率: 30FPS

  • 视频格式

    • 目前支持非透明视频和透明视频,可以通过接口参数IsAlpha来指定是否开启透明

    • 针对非透明视频目前视频格式只有MP4格式

      • MP4,固定绿幕色值的mp4视频, 色值为#0a9a38

    • 针对透明视频目前支持MOV、WEBM两种视频格式,可以通过接口参数AlphaFormat来指定透明视频格式:1、webm 2、mov

      • MOV:透明格式,生成的视频文件大小比较大

      • WEBM:透明格式,生成的视频文件大小相对MOV较小

  • 视频分辨率

    • 720P 和 1080P 横竖屏

  • 字幕

    • 支持字幕,字幕作为一个独立于视频的单独文件,支持下载,同时支持将字幕合并到数字人视频中

  • 背景图

    • 支持通过URL指定视频背景图,背景图分辨率需要与视频合成的分辨率保持一致,图片格式支持jpg、jpeg、png三种格式

  • 自定义数字人机位

    • 支持通过参数指定3D数字人的机位,目前支持以下7个机位,具体每个机位效果可以参考:数字人机位效果展示

      • 0: 全身近景机位

      • 1: 头部近景机位

      • 2: 全身远景机位

      • 3: 半身近景机位

      • 4: 半身远景机位

      • 5: 左边近景机位

      • 6: 右边近景机位

  • 自定义数字人角度

    • 支持通过参数指定3D数字人的角度,目前支持以下3个角度,具体每个角度效果可以参考:数字人角度效果展示

      • 0: 正面

      • 1: 左侧30度

      • 2: 右侧30度

  • 自定义数字人行业和特定动作

    • 支持参数指定数字人动作行业

    • 支持通过文本插入标签方式指定数字人播报动作,实现更加灵活的数字人动作控制,具体使用可以参考SSML使用

  • 自定义音频参数

    • 支持参数指定TTS发音人、音速、音调、音量

  • 最大存储时间

    • 支持7天在线存储,7天后视频内容将无法下载

  • 支持最大输入1000个文本字符(SSML标签不计入)

    • 支持纯文本进行数字人视频合成

    • 支持阿里云语音合成服务的SSML标记语言,针对一些文本读音、数字人动作等进行自定义,参考:SSML使用

  • 支持传入最长30分钟的音频

  • 支持事件回调机制

重要
  • 如果您期望获取透明通道的视频,可以直接设置IsAlpha为true,平台将生产MOV格式的透明视频,生成的视频文件大小比较大,1分钟时长的视频大小可能达到1G;同时您还可以设置IsAlpha为false,从而生成MP4视频格式,

  • 视频文件大小会小很多,然后通过第三方媒体制作工具针对绿幕视频进行抠图得到透明视频,我们已经提供绿幕相关色值。

  • 视频文件和字幕文件有效下载时间是7天,请在生成完成之后尽快下载视频和字幕,过期将无法再下载。

SSML使用

在Text字段直接传入SSML文本即可。SSML规则参考数字人服务SSML使用指南

前置条件

下述介绍使用3D数字人视频合成需要提前完成的步骤,每个步骤都需要完成才能顺利使用3D数字人视频合成服务。

  1. 申请阿里云账号, 具体参考准备工作

  2. 下单购买数字人视频合成服务(使用子账号的话,需要主账号提前授权对应的购买权限),具体参考开通服务

  3. 下单完成之后进入虚拟数字人开放平台控制台,获取对应的租户id信息和appId信息,具体可参考:一、开发者信息获取(TenantId + AppId)

技术接入

警告

请确保完成上述全部前置步骤,获取到阿里云账号的AccessKey ID和AccessKey Secret(点击获取),以及获取到对应数字人应用的tenantId和appId。

下面介绍使用3D数字人视频合成服务的完整对接步骤以及涉及到API。虚拟数字人开放平台的服务端API采用OpenAPI形式对外输出,具体对接方案见:服务端 API 接入

使用流程:视频合成服务是离线进行视频合成,所以流程是先提交视频合成任务,得到任务TaskUuid,然后拿着TaskUuid调用查询视频合成服务信息查询API,查询任务状态(这里需要轮询或者接收数字人回调事件通知,轮询周期最小间隔1s,建议3s),直到任务状态显示为已完成或者失败,状态为已完成的时候可以获取到对应的视频下载URL,然后直接通过URL可以下载到对应的视频。

1. SDK版本要求

重要

该功能需要升级虚拟数字人开放平台服务端SDK版本至1.0.5及以上。

2. 提交文本合成3D数字人视频任务

下面介绍文本合成3D数字人视频任务的接口。

代码示例:

参考OpenAPI官网调试页面,可在线直接填写参数并执行测试。

接口描述

参数

类型

是否必需

说明

TenantId

Long

租户ID,从虚拟数字人开放平台中获取的TenantId。参考:租户ID(TenantId)获取

App

Object

开发者应用信息。

App.AppId

String

开发者信息AppId,从虚拟数字人开放平台中获取。参考:AppId获取

Title

String

任务标题:

  • 任务标题最长64个字。

  • UTF-8编码格式

Text

String

合成的文本,最大支持1000个字符(SSML标签不计入);同时支持纯文本和SSML文本

VideoInfo

Object

视频设置。

VideoInfo.Resolution

Number

视频分辨率, 默认1

  • 1:720x1280竖屏

  • 2:1280x720横屏

  • 3:1080x1920竖屏

  • 4:1920x1080横屏

VideoInfo.IsAlpha

Boolean

是否需要透明通道, 默认false。

  • true: 开启透明通道,视频格式为MOV

  • false:不开启透明通道,视频格式为MP4,包含绿幕

VideoInfo.AlphaFormat

Integer

透明视频格式,针对透明视频目前支持MOV、WEBM两种视频格式:

  • 1:webm

  • 2:mov

VideoInfo.SubtitleEmbedded

Boolean

是否将字幕合并到视频中,默认值false

  • true:字幕合并到视频中

  • false:字幕不合并到视频中,会提供一个单独的字幕文件供下载使用

VideoInfo.BackgroundImageUrl

String

指定视频背景图URL。

  • 必须是有效可访问的URL背景图片地址,且背景图片的分辨率必须要与生成的视频分辨率保持一致。

  • 目前支持jpg,jpeg,png的图片格式。

(请升级SDK到最新版本使用)

AvatarInfo

Object

数字人相关配置

AvatarInfo.code

String

数字人形象code,从虚拟数字人开放平台-3D资产页面获取,不传则使用应用配置的默认形象点击查看形象code获取方法

AvatarInfo.Locate

Integer

数字人机位

  • 0: 全身近景机位,默认机位

  • 1: 头部近景机位

  • 2: 全身远景机位

  • 3: 半身近景机位

  • 4: 半身远景机位

  • 5: 左边近景机位

  • 6: 右边近景机位

具体每个机位效果可以参考:数字人机位效果展示

AvatarInfo.Angle

Integer

数字人角度

  • 0: 正面,默认角度

  • 1: 左侧30度

  • 2: 右侧30度

具体每个角度效果可以参考:数字人角度效果展示

AvatarInfo.IndustryCode

String

数字人动作行业code,默认值:default

  • default - 默认通用

  • kefu - 客服行业

  • live - 直播场景

AudioInfo

object

音频相关配置,不传则使用资产中配置的默认值。

说明

部分阿里云语音合成的音色没有经过效果验证,可能会出现效果上的差异

AudioInfo.Voice

String

TTS播报发音人code,从虚拟数字人开放平台-3D资产管理页面获取,参考文档:获取发音人code,不传则使用资产中配置的发音人。

AudioInfo.Volume

Integer

TTS播报声音音量,取值范围:0~100,不传则使用资产中配置的默认值。

AudioInfo.SpeechRate

Integer

TTS播报声音语速,取值范围:-500~500,不传则使用资产中配置的默认值。

[-500, 0, 500] 对应的语速倍速区间为 [0.5, 1.0, 2.0]。

-500表示基准语速的0.5倍速; 0表示基准语速的1倍速。1倍速是指模型默认输出的合成语速,语速会依据每一个发音人略有不同,大概每秒钟4个字左右; 500表示基准语速的2倍速;

计算方法如下:

0.8倍速(1-1/0.8)/0.002 = -125

1.2倍速(1-1/1.2)/0.001 = 166

AudioInfo.PitchRate

Integer

TTS播报声音语调,取值范围:-500~500,不传则使用资产中配置的默认值。

Callback

Boolean

本次视频合成任务是否需要事件回调,默认false不回调。平台支持在任务开始和任务结束时进行事件回调,具体可参考文档:数字人回调事件通知

CallbackParams

String

回调时需要平台透传的一些参数,传入该参数会在回调时添加在事件内容的callbackParams字段。

json格式字符串,callback=false时不生效。

重要

3. 提交音频合成3D数字人视频任务

下面介绍音频合成3D数字人视频任务的接口。接口大部分参数与文本合成接口类似。

代码示例:

参考OpenAPI官网调试页面,可在线直接填写参数并执行测试。

接口描述

参数

类型

是否必需

说明

TenantId

Long

租户ID,从虚拟数字人开放平台中获取的TenantId。参考:租户ID(TenantId)获取

App

Object

开发者应用信息。

App.AppId

String

开发者信息AppId,从虚拟数字人开放平台中获取。参考:AppId获取

Title

String

任务标题:

  • 任务标题最长64个字。

  • UTF-8编码格式

Url

String

音频的地址url,要求音频时长小于30分钟

VideoInfo

Object

视频设置。

VideoInfo.Resolution

Number

视频分辨率, 默认1

  • 1:720x1280竖屏

  • 2:1280x720横屏

  • 3:1080x1920竖屏

  • 4:1920x1080横屏

VideoInfo.IsAlpha

Boolean

是否需要透明通道, 默认false。

  • true: 开启透明通道,视频格式为MOV

  • false:不开启透明通道,视频格式为MP4,包含绿幕

VideoInfo.AlphaFormat

Integer

透明视频格式,针对透明视频目前支持MOV、WEBM两种视频格式。

1:webm

2:mov

VideoInfo.BackgroundImageUrl

String

指定视频背景图URL。

  • 必须是有效可访问的URL背景图片地址,且背景图片的分辨率必须要与生成的视频分辨率保持一致。

  • 目前支持jpg,jpeg,png的图片格式。

(请升级SDK到最新版本使用)

AvatarInfo

Object

数字人相关配置

AvatarInfo.code

String

数字人形象code,从虚拟数字人开放平台-3D资产页面获取,不传则使用应用配置的默认形象(点击查看形象code获取方法

AvatarInfo.Locate

Integer

数字人机位

  • 0: 全身近景机位,默认机位

  • 1: 头部近景机位

  • 2: 全身远景机位

  • 3: 半身近景机位

  • 4: 半身远景机位

  • 5: 左边近景机位

  • 6: 右边近景机位

具体每个机位效果可以参考:数字人机位效果展示

AvatarInfo.Angle

Integer

数字人角度

  • 0: 正面,默认角度

  • 1: 左侧30度

  • 2: 右侧30度

具体每个角度效果可以参考:数字人角度效果展示

AvatarInfo.IndustryCode

String

数字人动作行业code,默认值:default

  • default - 默认通用

  • kefu - 客服行业

  • live - 直播场景

Callback

Boolean

本次视频合成任务是否需要事件回调,默认false不回调。平台支持在任务开始和任务结束时进行事件回调,具体可参考文档:数字人回调事件通知

CallbackParams

String

回调时需要平台透传的一些参数,传入该参数会在回调时添加在事件内容的callbackParams字段。

json格式字符串,callback=false时不生效。

重要
  • 平台大部分数字人形象支持音频合成视频,部分不支持音频合成视频。

    • 支持的形象:Bonnie、Stella、Daisy,以及基于这三个官方形象创建的自定义数字人形象;

    • 不支持的形象:Eric、Jill、Lisa、Mike、Ace,以及基于这几个官方形象创建的自定义数字人形象。

  • 详细的API信息可以参考提交3D音频合成视频任务

4. 获取3D数字人视频合成任务详情

当您提交一个任务并且获取到任务UUID之后, 您可以通过上面API返回的任务UUID通过轮询的方式获取任务详情,或者通过对接虚拟数字人开放平台提供的视频合成回调事件来监听任务的合成情况,回调事件具体可参考:数字人回调事件通知

代码示例:

参考OpenAPI官网调试页面,可在线直接填写参数并执行测试。

说明

详细的API信息可以参考:GetVideoTaskInfo - 查询视频合成任务详情。当任务状态为已完成时,可以从TaskResult中获取到对应的视频和字幕的URL,然后可以进行视频和字幕文件的下载。

警告

该接口调用方可能会进行轮询调用,强烈建议轮询间隔不要小于1s,建议设置为3s,当任务量较大的情况要增加间隔时间,避免出现接口限流异常(接口返回“error :code: 400, Request was denied due to user flow control. request id: xx-xx-xx-xx-xx”则表示触发了接口限流)。

5. 取消3D数字人视频合成任务

针对未开始的视频合成任务,您可以通过返回的任务UUID进行取消任务,已开始或者已完成的任务无法取消。

代码示例:

参考OpenAPI官网调试页面,可在线直接填写参数并执行测试。

说明

详细的API信息可以参考:CancelVideoTask - 取消视频合成任务

6. 完整的接入示例代码

数字人视频合成完整调用示例代码

7. 数字人机位效果展示

7.1 横屏效果

  • 0: 全身近景机位全身近景0

  • 1: 头部近景机位头部近景0

  • 2: 全身远景机位横屏-全身远景

  • 3: 半身近景机位横屏-半身近景

  • 4: 半身远景机位半身远景0

  • 5: 左边近景机位左边远景0

  • 6: 右边近景机位右边远景0

7.2 竖屏效果

  • 0: 全身近景机位全身近景0

  • 1: 头部近景机位头部近景0

  • 2: 全身远景机位全身远景0

  • 3: 半身近景机位半身近景0

  • 4: 半身远景机位半身远景0

  • 5: 左边近景机位左边远景0

  • 6: 右边近景机位右边远景0

8. 数字人角度效果展示

8.1 横屏效果(以全身近景机位为例展示角度效果)

  • 0: 正面,默认角度全身近景0

  • 1: 左侧30度全身近景30

  • 2: 右侧30度全身近景-30

8.2 竖屏效果(以全身近景机位为例展示角度效果)

  • 0: 正面,默认角度全身近景0

  • 1: 左侧30度全身近景30

  • 2: 右侧30度全身近景-30