如何对接数字人回调事件通知_虚拟数字人(DVH)-阿里云帮助中心

本文为您介绍虚拟数字人开放平台的回调事件通知的回调机制、使用流程及鉴权原理。

一、说明

虚拟数字人开放平台针对3D数字人流媒体服务的驱动能力会提供相应的驱动事件回调，目前仅支持HTTP接口方式。

二、事件回调接入流程

登录虚拟数字人开放平台控制台，在首页的开发者信息标签页（首页右上角）配置您的HTTP回调URL，并提交保存，保存时系统会自动回调一条VALIDATE事件校验该接口是否正确对接我们的回调鉴权协议，具体回调协议可参考下方，返回HTTP响应码200则校验通过，否则校验不通过，校验不通过则无法保存。
从开发者信息获取您的authKey信息，后续所有事件回调的鉴权都将使用这个authKey，请妥善保存。
对接我们的回调协议以及鉴权协议。
参考回调事件列表，找到您要对接的回调事件，按文档要求设置相应的参数，系统会在事件发生的时候自动调用您配置的HTTP回调地址。
您接收到HTTP回调之后，请确保在3s内返回相应结果（平台回调调用超时时间设置为3s），收到响应后数字人平台会判断http response的code值是否为200，非200则表示失败，针对回调失败平台会自动进行2次重试，第一次重试间隔500ms，第二次重试间隔1s，第二次重试失败之后则直接丢弃该事件。

重要

由于存在回调重试，您的回调接口请确保支持幂等，避免引起重复消费回调事件，可以根据事件ID进行幂等判断（回调内容中的eId字段）。

警告

为了保障数字人开放平台系统稳定性，当您的回调HTTP接口在多次调用失败之后，系统将对您的回调HTTP接口进行降级，降级之后在调用您的HTTP接口失败之后将不会进行重试，即被降级之后每条事件最多回调一次，失败则直接丢弃。

三、事件回调协议对接

3.1 事件回调协议

支持HTTP和HTTPS
POST协议

3.2 事件回调鉴权原理

鉴权方式

支持在HTTP（含HTTPS）回调时增加特定签名头，供回调消息接收服务端进行签名认证，以防止非法或无效请求

鉴权参数

在回调HTTP头部增加的具体鉴权参数如下：

字段	描述
VH-TIMESTAMP	UNIX时间戳，整型正数，固定长度13，1970年1月1日以来的毫秒数，表示回调请求发起时间。
VH-SIGNATURE	签名字符串，为32位MD5值，详细说明请参见下文签名算法。

签名算法

VH-SIGNATURE的计算依赖如下字段：

字段	示例	描述
TenantId	10000	租户id，可以从虚拟数字人开放平台获取。
VH-TIMESTAMP	1682065029925	UNIX时间戳，整型正数，固定长度13，1970年1月1日以来的毫秒数，表示回调请求发起时间，重试的时候VH-TIMESTAMP会变化。
AuthKey	TestAuthkey	密钥，16位字符串，可以从虚拟数字人开放平台获取。

将上述三个字段进行拼接，字段中间以竖线（|）分割，后计算MD5值，即：

MD5Content = tenantId|VH-TIMESTAMP|AuthKey
VH-SIGNATURE = md5sum(MD5Content)

示例：

VH-SIGNATURE = md5sum(10000|1682065029925|TestAuthkey) = 2b45a54a0a34e658e5c223d5892337a9

说明

不同开发语言的MD5类库可能存在差异，请通过上述示例进行本地校验，确保生成MD5是一致的。

接收方校验规则

接收方将自己从平台获取的TenantId、VH-TIMESTAMP取值、AuthKey字符串拼接后，进行MD5值计算，得到加密串，再将加密串与VH-SIGNATURE字段进行对比，如果不一致，则请求非法。

四、事件内容

事件内容放在Http请求的body中。不同事件对应的事件内容不同，可以通过eType字段值进行判断，以下是全事件通用的字段描述：

字段	描述	示例值
eId	唯一事件id，32位随机字符	8f503354c87f41338aab5b2935b38842
eType	事件类型，描述具体是什么事件	PLAY_START
eTime	13位时间戳，事件发生的时间	1682066517270

五、回调事件列表

5.1 VALIDATE事件

用于在虚拟数字人开放平台控制台配置回调URL的时候校验是否正确对接回调事件协议。

事件内容

字段	值
eType	VALIDATE

5.2 数字人流媒体服务事件

当前数字人流媒体服务支持针对3D数字人播报消息进行事件回调通知。

使用方法

调用SendText接口、SendVaml接口、SendCommand接口传递feedback=true。

事件列表

事件类型	事件说明	事件内容
PLAY_START	数字人开始播报事件	eId: xxxx eType: PLAY_START eTime: 1682068188783 sessionId: 调用SendMessage接口传递的SessionId字段） uniqueCode: 调用SendMessage接口传递的TextRequest.Id字段
PLAY_FINISH	数字人播报结束事件	eId: xxxx eType: PLAY_FINISH eTime: 1682068188783 sessionId: 调用SendMessage接口传递的SessionId字段） uniqueCode: 调用SendMessage接口传递的TextRequest.Id字段
PLAY_INTERRUPT	数字人播报被打断事件	eId: xxxx eType: PLAY_INTERRUPT eTime: 1682068188783 sessionId: 调用SendMessage接口传递的SessionId字段） uniqueCode: 调用SendMessage接口传递的TextRequest.Id字段

5.3 视频合成服务事件

3D数字人视频合成服务和2D数字人视频合成服务都支持。

使用方法

调用SubmitTextTo3DAvatarVideoTask接口、SubmitAudioTo3DAvatarVideoTask接口和SubmitTextTo2DAvatarVideoTask接口、SubmitAudioTo2DAvatarVideoTask接口传递callback=true。

事件列表

事件类型

事件说明

事件内容

VIDEO_START

视频合成任务开始执行

eId: xxxx

eType: VIDEO_START

eTime: 1682068188783

uuid: 调用SubmitTextToXXX和SubmitAudioToXXX接口返回的TaskUuid字段

callbackParams: 调用SubmitTextToXXX和SubmitAudioToXXX接口传递的CallbackParams原样带回

VIDEO_END

视频合成任务执行成功

eId: xxxx

eType: VIDEO_END

eTime: 1682068188783

uuid: 调用SubmitTextToXXX和SubmitAudioToXXX接口返回的TaskUuid字段

callbackParams: 调用SubmitTextToXXX和SubmitAudioToXXX接口传递的CallbackParams原样带回

success: true/false，执行成功or失败

code: 失败原因code，成功情况下没有

message: 失败原因描述，成功情况下没有

5.4 2D真人数字人形象创建回调事件

2D真人数字人形象创建会异步进行系统模型训练，通过创建API设置callback=true，系统会在训练结束时自动进行事件的回调。

使用方法

调用Create2dAvatar接口传递callback=true。

事件列表

事件类型	事件说明	事件内容
ASSETS_TRAIN_SUCCESS	2D真人数字人形象训练成功	eId: xxxx eType: ASSETS_TRAIN_SUCCESS eTime: 1682068188783 success:true characterCode: 调用Create2dAvatar接口返回的Code字段，即本次创建的数字人形象code reason: 失败原因
ASSETS_TRAIN_FAIL	2D真人数字人形象训练失败	eId: xxxx eType: ASSETS_TRAIN_FAIL eTime: 1682068188783 success: true characterCode: 调用Create2dAvatar接口返回的Code字段，即本次创建的数字人形象code reason: 失败原因
ASSETS_TRAIN_CONFIRM	2D真人数字人形象训练确认	eId: xxxx eType: ASSETS_TRAIN_CONFIRM eTime: 1682068188783 success: true characterCode: 调用Create2dAvatar接口返回的Code字段，即本次创建的数字人形象code reason: 失败原因