文档

数字人回调事件通知

更新时间:
重要

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

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

一、说明

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

二、事件回调接入流程

  1. 登录虚拟数字人开放平台控制台,在首页的开发者信息标签页(首页右上角)配置您的HTTP回调URL,并提交保存,保存时系统会自动回调一条VALIDATE事件校验该接口是否正确对接我们的回调鉴权协议,具体回调协议可参考下方,返回HTTP响应码200则校验通过,否则校验不通过,校验不通过则无法保存。image.png

  2. 从开发者信息获取您的authKey信息,后续所有事件回调的鉴权都将使用这个authKey,请妥善保存。

  3. 对接我们的回调协议以及鉴权协议。

  4. 参考回调事件列表,找到您要对接的回调事件,按文档要求设置相应的参数,系统会在事件发生的时候自动调用您配置的HTTP回调地址。

  5. 您接收到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: 失败原因

  • 本页导读 (0)