4.3.5 声音设计API

<div style="max-width: 100%; margin: 20px auto;">
    
    <div style="background-color: #ffffff; border-radius: 8px; box-shadow: 0 2px 8px rgba(0,0,0,0.1); overflow: hidden; font-family: 'Comic Sans MS', cursive, sans-serif;">
        
        
        <div style="background-color: #F4F8FA; padding: 1px 10px; border-bottom: 1px solid #dee2e6; display: flex; justify-content: space-between; align-items: center;">
            <div style="color: #0E42D2; font-weight: bold;font-size: 1.3rem;">声音设计API概述</div>
            <div>
            </div>
        </div>
        
        <div style="padding: 25px; line-height: 29px; background-image: linear-gradient(transparent 26px, #dee2e6 27px, #dee2e6 27px, transparent 27px); background-size: 100% 28px; min-height: 100px; color: #333;">
            <div>声音设计API可基于用户输入的提示词，快速生成音色资源，为用户提供专业化的音色创作接口服务。文档包含服务说明、接口规范、核心功能接口及功能调用。</div>
			<a href="#服务介绍" style="color: #6f42c1; font-weight: 500;">
			<strong>- 1、服务介绍>>>点击跳转&emsp;&emsp;&emsp;</strong></a>
			&emsp;&emsp;&emsp;<a href="#接口说明" style="color: #6f42c1; font-weight: 500;">
			<strong>- 2、接口说明>>>点击跳转&emsp;&emsp;&emsp;</strong></a>
			<br><a href="#功能接口" style="color: #6f42c1; font-weight: 500;">
			<strong>- 3、功能接口>>>点击跳转&emsp;&emsp;&emsp;</strong></a>
			&emsp;&emsp;&emsp;<a href="#功能接口" style="color: #6f42c1; font-weight: 500;">
			<strong>- 4、合成调用>>>点击跳转&emsp;&emsp;&emsp;</strong></a>
            <div></div>
        </div>
        
        </div>
    </div>
</div>

## 1. 服务介绍
声音设计是依托大模型模型，依据用户文本描述生成专属音色资源的定制化能力。
<div style="display: flex; align-items: flex-start; gap: 16px; padding: 16px; background: #fff5f6; border-radius: 5px; border-left: 4px solid #e83e8c; box-shadow: 0 4px 12px rgba(255, 215, 0, 0.08); margin-bottom: 16px; transition: transform 0.2s ease, box-shadow 0.2s ease;">
  <div>
    <div style="font-weight: 600; margin-bottom: 4px;">温馨提示</div>
    <div style="font-size: 14px; line-height: 1.5;">1、本服务使用前需先联系讯飞商务获取授权或发送邮件到 aiui_support@iflytek.com 提交申请。</div>
    <div style="font-size: 14px; line-height: 1.5;">2、接口调用前，指定的设备（SN）需要先集成AIUI SDK或API完成一次交互请求（即代表设备完成AIUI绑定授权注册）。</div>
    <div style="font-size: 14px; line-height: 1.5;">3、每个设备（SN）最多注册绑定3个资源id。</div>
  </div>
</div>

本协议主要提供复刻资源管理服务，包括**资源注册**、**资源查询**、**资源删除**、**资源清除**。具体合成调用需再交互服务API或AIUI SDK中具体实现。

## 2. 接口说明

### 请求地址
> http[s]://aiui.xf-yun.com

### 接口鉴权
具体鉴权参数构建见[鉴权文档](https://aiui-doc.xf-yun.com/project-1/doc-404/ "大模型API服务鉴权")说明。
<div style="display: flex; align-items: center; background-color: #fff3cd; border-left: 6px solid #ffc107; border-radius: 4px; padding: 12px 16px; gap: 8px;">
    <div style="width: 30px; height: 30px; flex-shrink: 0;">
        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
            <path d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"/>
        </svg>
    </div>
    <div style="flex: 1; line-height: 1.6;">
	<h3 style="margin: 0 0 6px 0; font-weight: 600;">注意：</h3>
        <p style="margin: 0; font-size: 0.95rem;">鉴权的时间戳有时效性，建议每次请求鉴权时都实时的获取最新时间戳，生成鉴权参数</p>
    </div>
</div>

## 3. 功能接口

###  3.1. 资源注册
根据用户输入的音频进行声音设计，返回资源id。1个SN最多同时绑定注册3个资源，删除已有资源后可继续注册。

- METHOD: POST
- PATH: /v3/aiint/voice-create/sgen/reg
- Content-Type: multipart/form-data

- HTTP 请求示例：

```java
POST /v3/aiint/voice-create/sgen/reg HTTP/1.1
Host: 127.0.0.1:9996
Content-Length: 412
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="appid"

5c8b403a
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="sn"

12334454543dfsdfsf
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="prompt"

一位17-19岁的男生，理工科学霸，性格理性冷静、严谨认真。音色清晰干练，沉稳睿智，语气平和理性，语速中等，节奏平稳流畅，适合数理化知识讲解和学习方法分享。
------WebKitFormBoundary7MA4YWxkTrZu0gW--
```

`表单参数`说明

| 参数名 | 类型   | 说明                               | 必需 | 示例               |
| ------ | ------ | ---------------------------------- | ---- | ------------------ |
| appid  | string | AIUI应用appid                      | 是   | 5c8b403a           |
| sn     | string | 设备sn号，已经激活的设备sn号，长度不超过32位 | 是   | 12334454543dfsdfsf |
| prompt   | string | 声音描述prompt，必须包含：年龄、性别、音色特点；每次创造的声音会有随机变化      | 否   | -                  |

`返回值`示例:
```json
  {
      "sid": "acm00010034@dx191749d8e5d0001562",
      "code": 0,
      "msg": "success",
      "data": {
          "res_id": "fsdfwee234324"
      }
  }
```

`返回值参数字段`说明：

| 参数名      | 类型   | 说明            | 必需 | 示例          |
| ---------- | ----- | -------------   | ---- | -----------  |
| sid         | string | 请求标识       | 是   | -             |
| code        | int    | 状态码，0 成功，非0表示请求处理失败   | 是   | 0    |
| msg         | string | 描述           | 是   | -             |
| data        | object | 返回数据        | 否   | -             |
| data.res_id | string | 成功返回的资源id，对应交互大模型接口中的：parameter.tts.res_id| 否   | fsdfwee234324 |

###  3.2. 资源查询
根据指定的SN号，查询当前设备已注册资源id。
- METHOD: GET
- PATH: /v3/aiint/voice-create/sgen/res?appid=5a66ccbb&sn=4b37ccbb1122c34389176ed5bc92000&res_id=naty1taermy

`参数字段`说明：

| 参数名 | 类型   | 说明                               | 必需 | 示例               |
| ------ | ------ | ---------------------------------- | ---- | ------------------ |
| appid  | string | AIUI应用appid                      | 是   | 5c8b403a           |
| sn     | string | 设备sn号，长度不超过32位 | 是   | 12334454543dfsdfsf |
| res_id   | string   | 当前设备已注册资源id       | 否   | naty1taermy  |

`返回值`示例:
```json
{
    "sid": "acm00940002@dx192d6d3ae917aa9992",
    "code": 0,
    "msg": "success",
    "data": [
        {
            "id": 73,
            "appid": "5c8b403a",
            "sn": "12334454543dfsdfsf",
            "res_id": "ioixvtc9gps",
            "create_time": "2024-09-12 16:56:17"
        },
        {
            "id": 3,
            "appid": "5c8b403a",
            "sn": "12334454543dfsdfsf",
            "res_id": "fsdfwee234324",
            "create_time": "2024-08-19 19:27:29"
        }
    ]
}
```

`返回值参数字段`说明：

| 参数名      | 类型   | 说明            | 必需 | 示例          |
| ---------- | ----- | -------------   | ---- | -----------  |
| sid         | string | 请求标识       | 是   | -             |
| code        | int    | 状态码，0 成功，非0表示请求处理失败   | 是   | 0    |
| msg         | string | 描述           | 是   | -             |
| data        | object | 返回数据        | 否   | -             |
|	data[i].id	|	int	|	资源id，自增主键	|	是	|	1	|
|	data[i].appid	|	string	|	应用id	|	是	|	-	|
|	data[i].sn	|	string	|	设备sn号	|	是	|	-	|
|	data[i].res_id	|	string	|	资源id，合成时使用	|	是	|	-	|
|	data[i].create_time	|	string	|	资源创建时间	|	是	|	-	|

### 3.3. 资源删除
根据指定的SN号下注册存在的资源id，删除该资源id信息。
- METHOD: DELETE
- PATH: /v3/aiint/voice-create/sgen/del
- Content-Type: application/json

`参数字段`说明：

| 参数名 | 类型   | 说明                               | 必需 | 示例               |
| ------ | ------ | ---------------------------------- | ---- | ------------------ |
| appid  | string | AIUI应用appid                      | 是   | 5c8b403a           |
| sn     | string | 设备sn号，已经激活的设备sn号，长度不超过32位 | 是   | 12334454543dfsdfsf |
| res_id   | string   | 当前设备已注册资源id       | 是   | ioixvtc9gps  |

`返回值`示例:
```json
 {
      "sid": "acm00010034@dx191749d8e5d0001562",
      "code": 0,
      "msg": "success",
      "data": null
  }
```

`返回值参数字段`说明：

| 参数名      | 类型   | 说明            | 必需 | 示例          |
| ---------- | ----- | -------------   | ---- | -----------  |
| sid         | string | 请求标识       | 是   | -             |
| code        | int    | 状态码，0 成功，非0表示请求处理失败   | 是   | 0    |
| msg         | string | 描述           | 是   | -             |
| data        | object | 返回数据        | 否   | -             |

### 3.4. 资源清除
根据指定的SN号，删除该sn下所有的资源id信息。
- METHOD: DELETE
- PATH: /v3/aiint/voice-create/sgen/clean
- Content-Type: application/json

`参数字段`说明：

| 参数名 | 类型   | 说明                               | 必需 | 示例               |
| ------ | ------ | ---------------------------------- | ---- | ------------------ |
| appid  | string | AIUI应用appid                      | 是   | 5c8b403a           |
| sn     | string | 设备sn号，已经激活的设备sn号，长度不超过32位 | 是   | 12334454543dfsdfsf |

`返回值`示例:
```json
  {
      "sid": "acm00010034@dx191749d8e5d0001562",
      "code": 0,
      "msg": "success",
      "data": [ "nwvz3uojq41", "nwvz3uojq42" ]
  }
```

`返回值参数字段`说明：

| 参数名      | 类型   | 说明            | 必需 | 示例          |
| ---------- | ----- | -------------   | ---- | -----------  |
| sid         | string | 请求标识       | 是   | -             |
| code        | int    | 状态码，0 成功，非0表示请求处理失败   | 是   | 0    |
| msg         | string | 描述           | 是   | -             |
| data        | []string | 返回数据，删除的所有资源id        | 否   | -             |

## 4. 合成调用
在极速超拟人交互链路中，声音设计合成调用见 【[合成能力使用](https://aiui-doc.xf-yun.com/project-1/doc-788/ "4.3.5合成能力使用")】文档说明。

<div style="display: flex; align-items: flex-start; gap: 16px; padding: 16px; background: #fff5f6; border-radius: 5px; border-left: 4px solid #e83e8c; box-shadow: 0 4px 12px rgba(255, 215, 0, 0.08); margin-bottom: 16px; transition: transform 0.2s ease, box-shadow 0.2s ease;">
  <div>
    <div style="font-weight: 600; margin-bottom: 4px;">温馨提示</div>
	<div style="font-size: 14px; line-height: 1.5;">声音设计新增创建版本指定后，合成使用时需要注意vcn参数固定为<strong>x7_design。</strong></div>
  </div>
</div>