# 声音注册查询
#### 前提条件
- 确保已按照[配置Java环境](https://support.huaweicloud.com/sdkreference-sis/sis_05_0041.html)配置配置完毕。
- 请参考[SDK（websocket）](https://support.huaweicloud.com/sdkreference-sis/sis_05_0004.html)获取最新版本SDK包。
- 仅上海一局点支持该接口。
 
#### 初始化Client
初始化vcsClient，详见[表1]。
 表1vcsClient 
| 参数名称            | 是否必选 | 参数类型   | 描述                                                                                     |
|:---|:---|:---|:---|
| ak              | 是    | String | 用户的ak，可参考[AK/SK认证](https://support.huaweicloud.com/sdkreference-sis/sis_05_0003.html)。 |
| sk              | 是    | String | 用户的sk，可参考[AK/SK认证](https://support.huaweicloud.com/sdkreference-sis/sis_05_0003.html)。 |
| region          | 是    | String | 区域，如：cn-east-3，具体请参考[终端节点](https://support.huaweicloud.com/api-sis/sis_03_0004.html)。  |
| projectId       | 是    | String | 项目ID，同region一一对应，参考获取项目ID。                                                             |
| serviceEndpoint | 否    | String | 终端节点，一般使用默认即可，详见[终端节点](https://support.huaweicloud.com/api-sis/sis_03_0004.html)。      |
   
#### 请求参数（声音注册）
请求类型registerQueryRequest，详见[表2]。
 表2registerQueryRequest 
| 参数名称   | 是否必选 | 参数类型   | 描述                                       |
|:---|:---|:---|:---|
| path   | 是    | String | 待注册声音路径，要求采样率不低于16k。                     |
| config | 是    | Object | 详见[表3]。 |
   
 表3Config 
| 参数名称      | 是否必选 | 参数类型   | 描述                                                                        |
|:---|:---|:---|:---|
| voiceName | 是    | String | 注册声音的名称，不能以数字、下划线开头。仅包含大、小写英文字母、数字和下划线，且长度不超过20个字符。一个projectId下的声音名称不能重复。 |
| language  | 否    | String | data中语音数据的语种，取值"chinese"、"english"；默认是chinese。                            |
   
#### 请求参数（声音查询）
请求类型registerQueryRequest，详见[表4]。
 表4registerQueryRequent 
| 参数名称   | 是否必选 | 参数类型    | 描述                                                |
|:---|:---|:---|:---|
| limit  | 否    | Integer | 查询已注册的声音列表，每页查询显示的条目数量，默认：10。                     |
| offset | 否    | Integer | 查询已注册的声音列表，页码偏移量，表示从此页码偏移量开始查询，offset大于等于0， 默认：0。 |
   
#### 响应参数（声音注册）
Java SDK响应结果为Json格式，正确响应详见[表5]，错误响应详见[表7]。
 表5响应参数说明 
| 参数名称    | 参数类型   | 描述                                               |
|:---|:---|:---|
| traceId | String | 服务内部的令牌，可用于在日志中追溯具体流程。                           |
| result  | Object | 注册声音响应，详见[表6]。 |
   
 表6result数据结构 
| 参数名称      | 参数类型   | 描述       |
|:---|:---|:---|
| voiceName | String | 注册声音的名称。 |
   
 表7错误响应 
| 参数名称      | 参数类型   | 描述                     |
|:---|:---|:---|
| errorCode | String | 调用失败时的错误码。 调用成功时无此字段。  |
| errorMsg  | String | 调用失败时的错误信息。 调用成功时无此字段。 |
   
#### 响应参数（声音查询）
Java SDK响应结果为Json格式，正确响应详见[表5]，错误响应详见[表11]。
表8响应参数说明 
| 参数名称    | 参数类型   | 描述                                                |
|:---|:---|:---|
| traceId | String | 服务内部的令牌，可用于在日志中追溯具体流程。                            |
| result  | Object | 注册声音响应，详见[表9]。 |
   
 表9result数据结构 
| 参数名称   | 参数类型   | 描述                                                   |
|:---|:---|:---|
| voices | String | 注册成功的声音列表，详见[表10]。 |
   
 表10voice结构 
| 参数名称      | 参数类型   | 描述         |
|:---|:---|:---|
| voiceName | String | 注册成功的声音名称。 |
| language  | String | 注册成功的声音语种。 |
   
 表11错误响应 
| 参数名称      | 参数类型   | 描述                     |
|:---|:---|:---|
| errorCode | String | 调用失败时的错误码。 调用成功时无此字段。  |
| errorMsg  | String | 调用失败时的错误信息。 调用成功时无此字段。 |
   
#### 请求示例
- 说明："endpoint"即调用API的请求地址，不同服务不同区域的"endpoint"不同，具体请参见终端节点，当前仅支持上海一。
- 调用API，注册查询声音。
  ```
  package com.huawei.sis.demo.cn_demo;
  import com.huawei.sis.bean.AuthInfo;
  import com.huawei.sis.bean.SisConfig;
  import com.huawei.sis.bean.SisConstant;
  import com.huawei.sis.bean.request.RegisterVoiceRequest;
  import com.huawei.sis.bean.response.RegisterVoiceResponse;
  import com.huawei.sis.bean.response.VoicesResponse;
  import com.huawei.sis.client.VcsClient;
  import com.huawei.sis.exception.SisException;
  import com.huawei.sis.util.IOUtils;
  import com.huawei.sis.util.JsonUtils;
  import org.slf4j.Logger;
  import org.slf4j.LoggerFactory;
  /**
   * 声音复刻-声音注册和查询Demo
   * <p>
   * Copyright 2026 Huawei Technologies Co.,Ltd.
   */
  public class VcsRegisterAndRequest {
      /*
       * 1. 用户先录制一段声音，进行注册
       * 2. 录音数据，使用base64编码，大小不超过6MB。支持wav、mp3、m4a格式，采样率不小于16kHz，时长在5-25秒，支持单、双通道。
       * 2. 用户查询已经注册的声音信息(包括预置的声音）
       */
      private static final Logger log = LoggerFactory.getLogger(VcsRegisterAndRequest.class);
      // 认证用的ak和sk硬编码到代码中或者明文存储都有很大的安全风险，建议在配置文件或者环境变量中密文存放，使用时解密，确保安全；
      private String ak = System.getenv("HUAWEICLOUD_SDK_AK");
      private String sk = System.getenv("HUAWEICLOUD_SDK_SK");
      private String region = "";    // 区域，如cn-east-3
      private String projectId = ""; // 项目id，在我的凭证查看。参考https://support.huaweicloud.com/api-sis/sis_03_0008.html
      private String serviceEndPoint = "";  // 非必选，参考终端节点
      private String path = ""; // 用户录音的声音存放位置，文件格式为wav、mp3、m4a
      public static void main(String[] args) {
          VcsRegisterAndRequest vcsRegisterAndRequest = new VcsRegisterAndRequest();
          vcsRegisterAndRequest.RegisterAndRequest();
      }
      /**
       * 定义config，所有参数可选，设置超时时间等。
       *
       * @return SisConfig
       */
      private SisConfig getConfig() {
          SisConfig config = new SisConfig();
          // 设置连接超时，默认10000ms
          config.setConnectionTimeout(SisConstant.DEFAULT_CONNECTION_TIMEOUT);
          // 设置读取超时，默认10000ms
          config.setReadTimeout(SisConstant.DEFAULT_READ_TIMEOUT);
          // 设置代理, 一定要确保代理可用才启动此设置。 代理初始化也可用不加密的代理, new ProxyHostInfo(host, port);
          // 设置代理，可参考 config.setProxy(new ProxyHostInfo(host, port, user, password));
          return config;
      }
      /**
       * 声音复刻-声音注册和查询Demo
       */
      private void RegisterAndRequest() {
          // 两个接口可单独运行
          registerVoice(); // 声音注册接口
          listVoice();  // 声音查询接口
      }
      private void registerVoice() {
          try {
              // 1. 初始化AuthInfo
              // 定义authInfo，根据ak，sk，region，projectId
              AuthInfo authInfo = new AuthInfo(ak, sk, region, projectId);
              // 设置config，主要与超时有关
              SisConfig config = getConfig();
              VcsClient vcsClient = new VcsClient(authInfo, config);
              // 2. 配置请求
              String data = IOUtils.getEncodeDataByPath(path);
              String voiceName = "";  // 待注册的用户声音名称, 多次使用同一个名称注册, 会报错名称重复
              String language = "chinese"; // 待注册的用户声音语种
              RegisterVoiceRequest request = new RegisterVoiceRequest(voiceName, data, language);
              // 3. 发送请求，获取响应。
              RegisterVoiceResponse response = vcsClient.registerVoice(request);
              log.info(JsonUtils.obj2Str(response, true));
          } catch (SisException e) {
              log.info("error_code:" + e.getErrorCode() + " error_msg:" + e.getErrorMsg());
          }
      }
      private VoicesResponse listVoice() {
          try {
              // 1. 初始化AuthInfo
              // 定义authInfo，根据ak，sk，region，projectId
              AuthInfo authInfo = new AuthInfo(ak, sk, region, projectId, serviceEndPoint);
              // 设置config，主要与超时有关
              SisConfig config = getConfig();
              VcsClient vcsClient = new VcsClient(authInfo, config);
              // 2. 发送请求，获取响应。具体结果可通过response.getXX获取, 下面取前10个音色
              VoicesResponse response = vcsClient.query(10, 0);
              log.info(JsonUtils.obj2Str(response, true));
              return response;
          } catch (SisException e) {
              log.info("error_code:" + e.getErrorCode() + " error_msg:" + e.getErrorMsg());
              return null;
          }
      }
  }
  ```
  
 
#### 响应示例
状态码：200
成功响应示例（注册声音）
```
{ 
   "trace_id": "567e8537-a89c-13c3-a882-826321939651", 
   "result":{ 
     "voice_name": "test_xiaoming"
   } 
 }
```
状态码：200
成功响应示例（查询声音）
```
{ 
   "trace_id": "567e8537-a89c-13c3-a882-826321939651", 
   "result":{ 
     "voices": [
        {
          "voice_name": "test_xiaoming",
          "language": "chinese"
        }
   } 
 }
```
状态码：400
失败响应示例（注册查询声音）
```
{  
    "error_code": "SIS.***",  
    "error_msg": "***"          
}
```