本文档介绍如何驱动数字人进行播报、以及执行对应的指令,以及如何通过使用SSML文本实现自定义数字人播报的动作。涉及数字人的播报系列API:SendText - 发送普通文本消息、SendVaml - 发送vaml文本消息、SendCommand - 发送指令消息。
播报API介绍
平台提供了三个播报相关的API:
SendText - 发送普通文本消息:用于发送普通文本消息,支持纯文本和SSML文本(SSML文本可用于自定义TTS发音效果,以及实现自定义数字人动作),用于驱动数字人进行简单的文本播报。
SendVaml - 发送VAML文本消息:用于发送VAML文本消息,用于驱动数字人在播报的同时实现一些复杂的行为,如动作、字幕、卡片等元素的联动。
SendCommand - 发送指令消息:用于发生指令消息,用于驱动数字人执行一些相应的指令,如停止当前正在播报内容。
用户可通过调用不同的接口实现不同的需求,下面详细介绍每个接口的定义和使用。
1. SendText - 发送普通文本消息
1.1 接口介绍
接口描述:用于发送普通文本消息,支持纯文本和SSML文本,用于驱动数字人进行简单的文本播报。
API文档地址:SendText - 发送普通文本消息。
API在线调试地址:https://next.api.aliyun.com/api/avatar/2022-01-30/SendText?tab=DEMO&lang=JAVA。
1.2 参数介绍
名称 | 类型 | 必填 | 描述 |
TenantId | long | 是 | 租户ID,从虚拟数字人开放平台中获取的TenantId。可参考文档:开发者信息获取。 |
SessionId | string | 否 | 会话 SessionID。通过“启动一个数字人”API的返回值获取。 |
Text | string | 是 | 播报文本的内容,目前支持纯文本和阿里云智能语音合成的SSML标记语言(SSML使用方案请参考数字人服务SSML使用指南),最大文本长度1000字(不包含标签)。 |
Interrupt | boolean | 否 | 本次播报请求是否打断当前正在播报的内容,默认值为true。 |
UniqueCode | string | 是 | 播报请求唯一code,最大支持64位,需要保持唯一,可使用UUID。 |
Feedback | boolean | 否 | 是否需要在数字人进行播报该条消息的时候进行回调通知,默认值false,具体可参考:数字人回调事件通知。 |
StreamExtension | object | 否 | 流式播报扩展对象,不是流式播报,不传该对象。用户需要自己切分文本片段(比如说按照标点符号切分),数字人按照提交文本顺序连续的进行播报。 |
| boolean | 否 | 是否流式播报 |
| integer | 否 | 流式播报第几片段 |
| string | 否 | 片段类型,是开始、中间、结束
|
1.3 代码示例
package com.aliyun.sample;
import com.aliyun.tea.*;
public class Sample {
/**
* 使用AK&SK初始化账号Client
* @param accessKeyId
* @param accessKeySecret
* @return Client
* @throws Exception
*/
public static com.aliyun.avatar20220130.Client createClient(String accessKeyId, String accessKeySecret) throws Exception {
com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
// 必填,您的 AccessKey ID
.setAccessKeyId(accessKeyId)
// 必填,您的 AccessKey Secret
.setAccessKeySecret(accessKeySecret);
// 访问的域名
config.endpoint = "avatar.cn-zhangjiakou.aliyuncs.com";
return new com.aliyun.avatar20220130.Client(config);
}
public static void main(String[] args_) throws Exception {
java.util.List<String> args = java.util.Arrays.asList(args_);
// 请确保代码运行环境设置了环境变量 ALIBABA_CLOUD_ACCESS_KEY_ID 和 ALIBABA_CLOUD_ACCESS_KEY_SECRET。
// 工程代码泄露可能会导致 AccessKey 泄露,并威胁账号下所有资源的安全性。以下代码示例使用环境变量获取 AccessKey 的方式进行调用,仅供参考,建议使用更安全的 STS 方式,更多鉴权访问方式请参见:https://help.aliyun.com/document_detail/378657.html
com.aliyun.avatar20220130.Client client = Sample.createClient(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
com.aliyun.avatar20220130.models.SendTextRequest sendTextRequest = new com.aliyun.avatar20220130.models.SendTextRequest()
// 租户id,从虚拟数字人开放平台获取
.setTenantId(${tenantId})
// sessionId,调用StartInstance启动数字人服务的返回值获取
.setSessionId("${sessionId}")
// 播报的文本
.setText("虚拟数字人播报测试文本")
// 播报SSML文本
// .setText("<speak>大家好<vh-action code=\"animation_6746\" interrupt=\"true\"/>,这是一段虚拟数字人播报测试文本,欢迎大家! </speak>")
// 本次播报是否打断数字人当前正在播报的内容
.setInterrupt(true)
// 本地播报的唯一id
.setUniqueCode("3f71f630-96a5-44ae-9702-69f9ebd7642c")
// 是否需要回调通知本次播报状态
.setFeedback(false);
com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
try {
SendTextResponse response = client.sendTextWithOptions(sendTextRequest, runtime);
SendTextResponseBody responseBody = response.getBody();
if (null != responseBody.getSuccess() && responseBody.getSuccess()) {
// 调用成功
System.out.println(responseBody.getData());
} else {
// 调用失败
}
} catch (TeaException error) {
// 如有需要,请打印 error
com.aliyun.teautil.Common.assertAsString(error.message);
} catch (Exception _error) {
TeaException error = new TeaException(_error.getMessage(), _error);
// 如有需要,请打印 error
com.aliyun.teautil.Common.assertAsString(error.message);
}
}
}
1.4 通过发送SSML文本实现自定义TTS播报效果和自定义数字人动作
通过直接在Text字段传入SSML文本,可以实现自定义TTS播报效果和自定义数字人动作
SSML格式和支持的标签可以参考文档:SSML支持范围。
可以通过SSML支持的<vh-action>标签实现自定义数字人动作,需要从控制台的资产中心获取指定数字人的动作code,可以参考文档:获取数字人动作code。注意:不同数字人支持不同的动作,动作code必须与使用的数字人形象匹配,否则不生效。
自定义数字人动作代码示例:
com.aliyun.avatar20220130.models.SendTextRequest sendTextRequest = new com.aliyun.avatar20220130.models.SendTextRequest()
// 租户id,从虚拟数字人开放平台获取
.setTenantId(${tenantId})
// sessionId,调用StartInstance启动数字人服务的返回值获取
.setSessionId("${sessionId}")
// 播报SSML文本
.setText("<speak>大家好<vh-action code=\"animation_6746\" interrupt=\"true\"/>,这是一段虚拟数字人播报测试文本,欢迎大家! </speak>")
// 本次播报是否打断数字人当前正在播报的内容
.setInterrupt(true)
// 本地播报的唯一id
.setUniqueCode("3f71f630-96a5-44ae-9702-69f9ebd7642c")
// 是否需要回调通知本次播报状态
.setFeedback(false);
2. SendVaml - 发送VAML文本消息
2.1 接口介绍
接口描述:用于发送VAML文本消息,用于驱动数字人在播报的同时实现一些复杂的行为,如动作、字幕、卡片等元素的联动。
API文档地址:SendVaml - 发送vaml文本消息。
API在线调试地址:https://next.api.aliyun.com/api/avatar/2022-01-30/SendVaml?lang=JAVA&tab=DEMO。
2.2 参数介绍
名称 | 类型 | 必填 | 描述 |
TenantId | long | 是 | 租户ID,从虚拟数字人开放平台中获取的TenantId。可参考文档:开发者信息获取。 |
SessionId | string | 否 | 会话 SessionID。通过“启动一个数字人”API的返回值获取。 |
Vaml | string | 是 | 播报的VAML文本,需要符合VAML协议请求,具体参考VAML协议接入指南。 |
2.3 代码示例
package com.aliyun.sample;
import com.aliyun.tea.*;
public class Sample {
/**
* 使用AK&SK初始化账号Client
* @param accessKeyId
* @param accessKeySecret
* @return Client
* @throws Exception
*/
public static com.aliyun.avatar20220130.Client createClient(String accessKeyId, String accessKeySecret) throws Exception {
com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
// 必填,您的 AccessKey ID
.setAccessKeyId(accessKeyId)
// 必填,您的 AccessKey Secret
.setAccessKeySecret(accessKeySecret);
// 访问的域名
config.endpoint = "avatar.cn-zhangjiakou.aliyuncs.com";
return new com.aliyun.avatar20220130.Client(config);
}
public static void main(String[] args_) throws Exception {
java.util.List<String> args = java.util.Arrays.asList(args_);
// 请确保代码运行环境设置了环境变量 ALIBABA_CLOUD_ACCESS_KEY_ID 和 ALIBABA_CLOUD_ACCESS_KEY_SECRET。
// 工程代码泄露可能会导致 AccessKey 泄露,并威胁账号下所有资源的安全性。以下代码示例使用环境变量获取 AccessKey 的方式进行调用,仅供参考,建议使用更安全的 STS 方式,更多鉴权访问方式请参见:https://help.aliyun.com/document_detail/378657.html
com.aliyun.avatar20220130.Client client = Sample.createClient(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
com.aliyun.avatar20220130.models.SendVamlRequest sendVamlRequest = new com.aliyun.avatar20220130.models.SendVamlRequest()
// 租户id,从虚拟数字人开放平台获取
.setTenantId(${tenantId})
// sessionId,调用StartInstance启动数字人服务的返回值获取
.setSessionId("${sessionId}")
// 播报的VAML文本
.setVaml("<?xml version=\"1.0\" encoding=\"utf-8\"?><scene interrupt=\"true\" uniqueCode=\"208afe29838f416cbaa0730fdcfd051a\"><section><avatar aiAction=\"true\"><action begin_index=\"8\" end_index=\"10\" code=\"animation_4984\" interrupt=\"true\"/><action begin_index=\"33\" end_index=\"40\" code=\"animation_4807\" interrupt=\"true\"/><action begin_index=\"56\" end_index=\"60\" code=\"animation_4812\" interrupt=\"true\"/></avatar><speech>这是一段数字人播报VAML测试文本,文本自定义了动作</speech></section></scene>");
com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
try {
SendVamlResponse response = client.sendVamlWithOptions(sendVamlRequest, runtime);
SendVamlResponseBody responseBody = response.getBody();
if (null != responseBody.getSuccess() && responseBody.getSuccess()) {
// 调用成功
System.out.println(responseBody.getData());
} else {
// 调用失败
}
} catch (TeaException error) {
// 如有需要,请打印 error
com.aliyun.teautil.Common.assertAsString(error.message);
} catch (Exception _error) {
TeaException error = new TeaException(_error.getMessage(), _error);
// 如有需要,请打印 error
com.aliyun.teautil.Common.assertAsString(error.message);
}
}
}
VAML文本消息目前仅支持3D数字人流媒体服务,2D数字人流媒体服务暂不支持。
3. SendCommand - 发送指令消息
3.1 接口介绍
接口描述:用于发生指令消息,用于驱动数字人执行一些相应的指令,如停止当前正在播报内容。
API文档地址:SendCommand - 发送指令消息。
API在线调试地址:https://next.api.aliyun.com/api/avatar/2022-01-30/SendCommand?tab=DEMO&lang=JAVA。
3.2 参数介绍
名称 | 类型 | 必填 | 描述 |
TenantId | long | 是 | 租户ID,从虚拟数字人开放平台中获取的TenantId。可参考文档:开发者信息获取。 |
SessionId | string | 否 | 会话 SessionID。通过“启动一个数字人”API的返回值获取。 |
Code | string | 是 | 指令code:INTERRUPT :打断当前数字人播报,让数字人停止说话,Content无需传内容。 |
Content | object | 否 | 指令内容,map类型,不同的指令需要不同的参数内容,部分指令不需要指令内容的可以不传改参数。 |
UniqueCode | string | 是 | 消息请求唯一code,最大支持64位,需要保持唯一,可使用UUID。 |
Feedback | boolean | 否 | 是否需要在数字人进行执行该条消息的时候进行回调通知,默认值false,具体可参考:数字人回调事件通知。 重要 当前INTERRUPT指令暂不支持事件回调 |
3.3 代码示例
package com.aliyun.sample;
import com.aliyun.tea.*;
public class Sample {
/**
* 使用AK&SK初始化账号Client
* @param accessKeyId
* @param accessKeySecret
* @return Client
* @throws Exception
*/
public static com.aliyun.avatar20220130.Client createClient(String accessKeyId, String accessKeySecret) throws Exception {
com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
// 必填,您的 AccessKey ID
.setAccessKeyId(accessKeyId)
// 必填,您的 AccessKey Secret
.setAccessKeySecret(accessKeySecret);
// 访问的域名
config.endpoint = "avatar.cn-zhangjiakou.aliyuncs.com";
return new com.aliyun.avatar20220130.Client(config);
}
public static void main(String[] args_) throws Exception {
java.util.List<String> args = java.util.Arrays.asList(args_);
// 请确保代码运行环境设置了环境变量 ALIBABA_CLOUD_ACCESS_KEY_ID 和 ALIBABA_CLOUD_ACCESS_KEY_SECRET。
// 工程代码泄露可能会导致 AccessKey 泄露,并威胁账号下所有资源的安全性。以下代码示例使用环境变量获取 AccessKey 的方式进行调用,仅供参考,建议使用更安全的 STS 方式,更多鉴权访问方式请参见:https://help.aliyun.com/document_detail/378657.html
com.aliyun.avatar20220130.Client client = Sample.createClient(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
com.aliyun.avatar20220130.models.SendCommandRequest sendCommandRequest = new com.aliyun.avatar20220130.models.SendCommandRequest()
// 租户id,从虚拟数字人开放平台获取
.setTenantId(${tenantId})
// sessionId,调用StartInstance启动数字人服务的返回值获取
.setSessionId("${sessionId}")
// 指令code
.setCode("INTERRUPT")
// 本地播报的唯一id
.setUniqueCode("3f71f630-96a5-44ae-9702-69f9ebd7642c")
// 是否需要回调通知本次播报状态
.setFeedback(false);
com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
try {
SendCommandResponse response = client.sendCommandWithOptions(sendCommandRequest, runtime);
SendCommandResponseBody responseBody = response.getBody();
if (null != responseBody.getSuccess() && responseBody.getSuccess()) {
// 调用成功
System.out.println(responseBody.getData());
} else {
// 调用失败
}
} catch (TeaException error) {
// 如有需要,请打印 error
com.aliyun.teautil.Common.assertAsString(error.message);
} catch (Exception _error) {
TeaException error = new TeaException(_error.getMessage(), _error);
// 如有需要,请打印 error
com.aliyun.teautil.Common.assertAsString(error.message);
}
}
}
指令消息目前仅支持3D数字人流媒体服务,2D数字人流媒体服务暂不支持。