服务端API接入

更新时间: 2023-12-05 19:33:07

介绍如何接入虚拟数字人开放平台的服务端API,虚拟数字人开放平台的服务端API使用阿里云的标准OpenAPI接入方案,目前API SDK支持Java、python等多种开发语言,具体支持的开发语言和SDK版本可到虚拟数字人开放平台SDK查看。

整体接入流程

针对数字人流媒体服务接入的整体流程如下图示(3D数字人流媒体服务和2D数字人流媒体服务接入流程一致):

image

以下以Java开发语言为例介绍虚拟数字人开放平台服务端SDK接入方案,其他语言可参考虚拟数字人开放平台SDK。关于RTC拉流端SDK接入可参考实时流媒体服务接入

1. API SDK引入

  • 针对Java应用在pom.xml中引入如下dependency获得虚拟数字人开放平台Java SDK

<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>avatar20220130</artifactId>
  <version>${latest_version}</version>
</dependency>
重要

Apache Maven官方仓库,请使用最新版本,点击此处获取。关于SDK的详细信息以及其他语言的SDK见虚拟数字人开放平台SDK

2. SDK初始化

升级版 SDK 中因为具备完整的参数处理、返回值处理以及请求逻辑,所以可以给不同云产品的 SDK 生成不同的 Client 并包含其产品下所有的 OpenAPI 请求方法,可以使不同云产品之间的身份及鉴权信息隔离,使用上更加安全,下面是产品数字人开放平台 SDK 初始化示例:

public static void main(String[] args) {
    Config config = new com.aliyun.teaopenapi.models.Config();
    config.setAccessKeyId("<accessKeyId>");
    config.setAccessKeySecret("<accessKeySecret>");
    config.setEndpoint("avatar.cn-zhangjiakou.aliyuncs.com");
    Client client = new Client(config);
}
说明

示例代码中的accessKeyId和accessKeySecret需要阿里云账号提前申请好(参考步骤三:创建访问密钥AccessKey);endPoint当前默认为avatar.cn-zhangjiakou.aliyuncs.com。

3. 请求OpenAPI

启动数字人流媒体服务

  • 启动一路默认数字人流媒体服务(将数字人渲染的视频流推流到阿里云RTC服务器,客户可通过阿里云RTC拉流SDK进行拉流显示)示例:

public static void main(String[] args) {    
    StartInstanceRequest startInstanceRequest = new StartInstanceRequest();
    // 租户ID从数字人开放平台的业务配置详情中获取
    startInstanceRequest.setTenantId(<tenantId>);
    // 业务AppId从数字人开放平台的业务配置详情中获取
    startInstanceRequest.setApp(new StartInstanceRequest.StartInstanceRequestApp().setAppId("<appId>"));
    startInstanceRequest.setUser(new StartInstanceRequest.StartInstanceRequestUser().setUserId("<userId>").setUserName("<userName>"));   
    StartInstanceResponse startInstanceResponse = client.startInstance(startInstanceRequest);

    // 获取启动后SessionId,在后续的文本播报接口中需要传入
    String sessionId = startInstanceResponse.getBody().getData().getSessionId();
}
说明

tenantId和appId需要在开通虚拟数字人开放平台之后获取;关于参数的更多信息可以参考API参考指南中的StartInstance - 启动一个数字人

该接口返回信息中包含sessionId字段,该字段是后续操作该数字人实例的唯一id,需要妥善保存,如果不慎丢失可通过QueryRunningInstance - 查询运行中的数字人实例API查询。

  • 启动一路RTMP推流数字人流媒体服务(将数字人渲染的视频流以RTMP协议推流到指定RTMP服务器,客户可通过对应的RTMP服务器的协议进行拉流显示,更多信息可参考3D推流数字人接入指南)示例:

public static void main(String[] args) {    
    StartInstanceRequest startInstanceRequest = new StartInstanceRequest();
    // 租户ID从数字人开放平台的业务配置详情中获取
    startInstanceRequest.setTenantId(<tenantId>);
    // 业务AppId从数字人开放平台的业务配置详情中获取
    startInstanceRequest.setApp(new StartInstanceRequest.StartInstanceRequestApp().setAppId("<appId>"));
    startInstanceRequest.setUser(new StartInstanceRequest.StartInstanceRequestUser().setUserId("<userId>").setUserName("<userName>"));
    //自定义RTMP
    String chanelType = "RTMP";
    Map<String, String> reqConfig = new HashMap<>();
    reqConfig.put("url", "<RTMP地址>");
    reqConfig.put("token", "<RTMP认证token>");
    startInstanceRequest.setChannel(new StartInstanceRequest.StartInstanceRequestChannel().setType(chanelType).setReqConfig(reqConfig));     
    StartInstanceResponse startInstanceResponse = client.startInstance(startInstanceRequest);

    // 获取启动后SessionId,在后续的文本播报接口中需要传入
    String sessionId = startInstanceResponse.getBody().getData().getSessionId();
}   
说明

该示例代码是展示虚拟数字人开放平台中的推流数字人的API调用方式,其中<RTMP地址>和<RTMP认证token>是想要推流的对应平台后台提供的RTMP推流信息,更多信息可以参考API参考指南中的StartInstance - 启动一个数字人中的ReqConfig参数描述。

该接口返回信息中包含sessionId字段,该字段是后续操作该数字人实例的唯一id,需要妥善保存,如果不慎丢失可通过QueryRunningInstance - 查询运行中的数字人实例API查询。

数字人播报文本

  • 启动数字人流媒体服务之后,播报一段文本。

public static void main(String[] args) {    
    SendMessageRequest sendMessageRequest = new SendMessageRequest();
    // 租户ID从数字人开放平台的业务配置详情中获取
    sendMessageRequest.setTenantId(<tenantId>);
    // 传入SessionId(从StartInstance返回值中获取)
    sendMessageRequest.setSessionId(<sessionId>);
    // 传入要播报的文本内容
    sendMessageRequest.setTextRequest(new SendMessageRequest.SendMessageRequestTextRequest().setCommandType("START").setSpeechText("你好,我是智慧数字人小萌,很高兴跟大家见面")
                .setId(UUID.randomUUID().toString()));
    SendMessageResponse sendMessageResponse = client.sendMessage(sendMessageRequest);
}
说明

该示例代码是展示通过文本让数字人进行播报,更多信息可以参考API参考指南中的SendMessage - 发送文本消息

结束数字人流媒体服务

  • 结束数字人流媒体服务

public static void main(String[] args) {    
    StopInstanceRequest stopInstanceRequest = new StopInstanceRequest();
    // 租户ID从数字人开放平台的业务配置详情中获取
    stopInstanceRequest.setTenantId(<tenantId>);
    // 传入SessionId(从StartInstance返回值中获取)
    stopInstanceRequest.setSessionId(<sessionId>);
    StopInstanceResponse stopInstanceResponse = client.stopInstance(stopInstanceRequest);
}
说明

更多信息可以参考API参考指南中的StopInstance - 停止一个数字人

警告

数字人的生命周期需要在服务端完成管理, 平台不会主动结束数字人流媒体服务。

关于以上API更多的详细使用方法可以进入API参考指南进行查看。

说明

推荐阅读下一篇文档:客户端SDK接入,了解客户端如何接入数字人实时流媒体服务。

上一篇: 创建并配置数字人项目 下一篇: 客户端SDK接入