文档

数字人播报API接入指南

更新时间:

本文档介绍如何驱动数字人进行播报、以及执行对应的指令,以及如何通过使用SSML文本实现自定义数字人播报的动作。涉及数字人的播报系列API:SendText - 发送普通文本消息SendVaml - 发送vaml文本消息SendCommand - 发送指令消息

播报API介绍

平台提供了三个播报相关的API:

  • SendText - 发送普通文本消息:用于发送普通文本消息,支持纯文本和SSML文本(SSML文本可用于自定义TTS发音效果,以及实现自定义数字人动作),用于驱动数字人进行简单的文本播报。

  • SendVaml - 发送VAML文本消息:用于发送VAML文本消息,用于驱动数字人在播报的同时实现一些复杂的行为,如动作、字幕、卡片等元素的联动。

  • SendCommand - 发送指令消息:用于发生指令消息,用于驱动数字人执行一些相应的指令,如停止当前正在播报内容。

用户可通过调用不同的接口实现不同的需求,下面详细介绍每个接口的定义和使用。

1. SendText - 发送普通文本消息

1.1 接口介绍

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

流式播报扩展对象,不是流式播报,不传该对象。用户需要自己切分文本片段(比如说按照标点符号切分),数字人按照提交文本顺序连续的进行播报。

  • IsStream

boolean

是否流式播报

  • Index

integer

流式播报第几片段

  • Position

string

片段类型,是开始、中间、结束

  • start:第一个开始片段

  • mid:中间的片段

  • end:最后一个结束片段

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 接口介绍

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 接口介绍

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指令暂不支持事件回调

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.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数字人流媒体服务暂不支持。

  • 本页导读 (0)