备案控制台
文档
产品文档
输入文档关键字查找
首页 虚拟数字人 数字人开放平台 开发参考 开发指南 数字人播报API接入指南

数字人播报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）
文档反馈