4.3.4 声音复刻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>
            <div></div>
        </div>
        
        </div>
    </div>
</div>

# 文档更新说明
<table border="0" class="docutils" style="width: 100%;">
	<colgroup>
		<col width="5%" />
		<col width="30%" />
		<col width="5%" />
	</colgroup>
	<tbody valign="top">
		<tr>
			<td align="center" valign="center"><b>版本</b></td>
			<td align="center" valign="center"><b>更新内容</b></td>
			<td align="center" valign="center"><b>更新时间</b></td>
		</tr>
		<tr>
			<td style="text-align: center; vertical-align: middle;">V1.0</td>
			<td valign="center">初始文档</td>
			<td style="text-align: center; vertical-align: middle;">2024.10.17</td>
		</tr>
		<tr>
			<td style="text-align: center; vertical-align: middle;">V1.1</td>
			<td valign="center">1、新增复刻新版本：omni_v1<br>2、优化相关接口说明</td>
			<td style="text-align: center; vertical-align: middle;">2026.01.04</td>
		</tr>
		<tr>
			<td style="text-align: center; vertical-align: middle;">V1.2</td>
			<td valign="center">1、资源注册接口新增支持在线url参数：data_url</td>
			<td style="text-align: center; vertical-align: middle;">2026.05.14</td>
		</tr>
	</tbody>
</table>

## 1. 服务介绍
声音复刻是录入一段音频生成AI定制音色的能力。
<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中具体实现。

`示例Demo`
点击超链接下载：[HTTP DEMO](https://gitee.com/iflytek-aiui/AIUICbmLiteDemo/tree/master/res-mngr/voice-clone "点击下载")

## 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: /v2/aiint/voice-clone/sgen/reg
- Content-Type: multipart/form-data

- HTTP 请求示例：

```java
POST /v2/aiint/voice-clone/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="data"; filename="/D:/文件/tts/2-正常音色文件-zzy.pcm"
Content-Type: <Content-Type header here>

(data)
------WebKitFormBoundary7MA4YWxkTrZu0gW--
```

`表单参数`说明

<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;">如果资源注册时data和data_url参数同时存在，服务端优先使用data数据</div>
  </div>
</div>

| 参数名 | 类型   | 说明                               | 必需 | 示例               |
| ------ | ------ | ---------------------------------- | ---- | ------------------ |
| appid  | string | AIUI应用appid                      | 是   | 5c8b403a           |
| sn     | string | 设备sn号，长度不超过32位 | 是   | 12334454543dfsdfsf |
| data   | file   | 音频文件。与 data_url 参数二选一使用即可      | 是   | -                  |
| data_url  | string | 在线音频下载地址，GET 请求可以直接下载 。 与 data 参数二选一使用即可    | 是   | -             |
| engine_version   | string   | 声音复刻版本：v4、omni_v1<br>默认取值：v4 （对应初始版本）                          | 否   | omni_v1                |

`注册音频文件格式要求`说明如下：
>   时长: 建议20s~40s
>   文件大小范围：[480KB, 3MB]
>   采样率: 24000
>   通道数: 1
>   位深: 16
>   编码格式: pcm原始音频

`返回值`示例:
```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| 否   | fsdfwee234324 |

###  3.2. 资源查询
根据指定的SN号，查询当前设备已注册资源id。
- METHOD: GET
- PATH: /v2/aiint/voice-clone/sgen/res?appid=5c8b403a&sn=12334454543dfsdfsf&res_id=ioixvtc9gps

`参数字段`说明：

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

`返回值`示例:
```json
{
    "sid": "acm00940002@dx192d6d3ae917aa9992",
    "code": 0,
    "msg": "success",
    "data": [
        {
            "id": 73,
            "appid": "5c8b403a",
            "sn": "12334454543dfsdfsf",
            "res_id": "ioixvtc9gps",
            "version": "v4",
            "create_time": "2024-09-12 16:56:17"
        },
        {
            "id": 3,
            "appid": "5c8b403a",
            "sn": "12334454543dfsdfsf",
            "res_id": "fsdfwee234324",
            "version": "v4",
            "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].version	|	string	|	资源版本：v4（旧）、omni_v1（新）	|	是	|	-	|
|	data[i].create_time	|	string	|	资源创建时间	|	是	|	-	|

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

`参数字段`说明：

| 参数名 | 类型   | 说明                               | 必需 | 示例               |
| ------ | ------ | ---------------------------------- | ---- | ------------------ |
| appid  | string | AIUI应用appid                      | 是   | 5c8b403a           |
| sn     | string | 设备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 | 返回数据        | 否   | -             |

## 4. 合成调用
在极速超拟人交互链路中，声音复刻合成调用见 【[4.3.5合成能力使用](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参数资源版本的取值关系</div>
  </div>
</div>

<table border="0" class="docutils" style="width: 100%;">
	<colgroup>
		<col width="5%" />
		<col width="5%" />
	</colgroup>
	<tbody valign="top">
		<tr>
			<td align="center" valign="center"><b>声复刻版本</b></td>
			<td align="center" valign="center"><b>vcn对应取值</b></td>
		</tr>
		<tr>
			<td style="text-align: center; vertical-align: middle;">v4</td>
			<td style="text-align: center; vertical-align: middle;">x5_clone</td>
		</tr>
		<tr>
			<td style="text-align: center; vertical-align: middle;">omni_v1</td>
			<td style="text-align: center; vertical-align: middle;">x6_clone</td>
		</tr>
	</tbody>
</table>