> ## Documentation Index
> Fetch the complete documentation index at: https://docs.senseaudio.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# SenseAudio 音色克隆

export const VoiceCloneErrorHeading = () => {
  useEffect(() => {
    const section = document.createElement("section");
    section.className = "api-section";
    const heading = document.createElement("h4");
    heading.id = "voice-clone-error-codes";
    heading.className = "api-section-heading-title border-b pb-2.5 border-gray-100 dark:border-gray-800";
    heading.textContent = "错误码";
    section.appendChild(heading);
    const table = document.createElement("table");
    table.className = "w-full text-sm mt-4";
    table.innerHTML = `
      <thead><tr><th>HTTP</th><th>code</th><th>含义</th></tr></thead>
      <tbody>
        <tr><td>400</td><td><code>invalid</code></td><td>本地请求解析或参数校验失败</td></tr>
        <tr><td>401</td><td><code>authentication_error</code></td><td>提供的 API 密钥不正确</td></tr>
      </tbody>`;
    section.appendChild(table);
    const placeHeading = () => {
      const responseHeading = Array.from(document.querySelectorAll(".api-section-heading-title")).find(node => (/^(响应|Response)$/).test(node.textContent.trim()));
      const responseSection = responseHeading?.closest(".api-section");
      if (responseSection && responseSection.nextElementSibling !== section) {
        responseSection.after(section);
      } else if (!responseSection) {
        const main = document.querySelector("main");
        if (main && section.parentElement !== main) {
          main.appendChild(section);
        }
      }
    };
    const observer = new MutationObserver(placeHeading);
    observer.observe(document.body, {
      childList: true,
      subtree: true
    });
    placeHeading();
    return () => {
      observer.disconnect();
      section.remove();
    };
  }, []);
  return null;
};

<VoiceCloneErrorHeading />

## 说明

使用已上传的参考音频生成克隆音色。调用前请先通过 [上传文件](/api-reference/endpoint/files/upload) 获取 `file_id`。

* **生成链路**：上传音频获取 `file_id` → 调用本接口生成音色 ID → 在 TTS 接口中使用该音色。
* **音色 ID**：本接口使用 `label` 作为自定义音色 ID，生成后在 `voice_setting.voice_id` 中传入该 `label`。
* **克隆模型**：当前使用 `sensenova-tts-multilingual-2.0`。

## 调用示例

### 1. 上传参考音频

```bash theme={null}
curl -X POST https://api.senseaudio.cn/v1/files/upload \
  -H "Authorization: <API_KEY>" \
  -F "purpose=voice_clone" \
  -F "file=@/path/to/voice.wav"
```

上传成功后，从返回结果中读取 `file.file_id`：

```json theme={null}
{
  "file": {
    "file_id": "file-KQGDEegFNcaWhpNWdoiPZj",
    "filename": "voice.wav",
    "bytes": 228778,
    "purpose": "voice_clone"
  }
}
```

### 2. 生成克隆音色

```bash theme={null}
curl --request POST \
  --url https://api.senseaudio.cn/v1/voice/clone \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "description": "温柔御姐，普通话，语气自然",
    "file_id": "file-KQGDEegFNcaWhpNWdoiPZj",
    "model": "sensenova-tts-multilingual-2.0",
    "text": "你好，这是我的克隆音色试听。",
    "label": "wenrou_yujie_001"
  }'
```

## 使用克隆音色

生成成功后，将 `label` 作为 `voice_setting.voice_id` 传入 [语音合成 HTTP](/api-reference/endpoint/tts/synthesize)：

```json theme={null}
{
  "model": "sensenova-tts-2.0",
  "text": "你好，这是使用克隆音色生成的音频。",
  "voice_setting": {
    "voice_id": "wenrou_yujie_001"
  }
}
```

## 与 Minimax 兼容接口的区别

| 项目 | SenseAudio 音色克隆 | Minimax 兼容音色克隆 |
| - | - | - |
| 路径 | `/v1/voice/clone` | `/v1/voice_clone` |
| 音色 ID 字段 | `label` | `voice_id` |
| 音色描述 | 支持 `description` | 不包含 `description` |
| 生成后使用方式 | `voice_setting.voice_id = label` | `voice_setting.voice_id = voice_id` |


## OpenAPI

````yaml POST /v1/voice/clone
openapi: 3.1.0
info:
  title: SenseAudio Open Platform API
  description: >-
    SenseAudio 开放平台
    API，覆盖语音合成、音频生成、语音识别、音色能力、音乐生成、图片生成、视频生成、智能体与大语言模型等能力。未显式说明的字段为依据素材文档推断。
  version: 1.0.0
servers:
  - url: https://api.senseaudio.cn
    description: 生产环境
security:
  - bearerAuth: []
paths:
  /v1/voice/clone:
    post:
      tags:
        - Voice
      summary: SenseAudio 音色克隆
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SenseAudioVoiceCloneRequest'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SenseAudioVoiceCloneResponse'
components:
  schemas:
    SenseAudioVoiceCloneRequest:
      type: object
      required:
        - description
        - file_id
        - model
        - text
        - label
      properties:
        description:
          type: string
          description: 音色描述
        file_id:
          type: string
          description: 上传音频返回的 file.file_id
        model:
          type: string
          default: sensenova-tts-multilingual-2.0
          example: sensenova-tts-multilingual-2.0
          description: 克隆模型
        text:
          type: string
          description: 用于试听克隆效果的示例文本
        label:
          type: string
          description: 自定义克隆音色标签，也是生成后的音色 ID
    SenseAudioVoiceCloneResponse:
      type: object
      properties:
        label:
          type: string
          description: 克隆音色 ID，对应请求中的 label
        name:
          type: string
          description: 音色名称
        description:
          type: string
          description: 音色描述
        created_at:
          type: integer
          description: 创建时间，UNIX 时间戳
        demo:
          type: string
          description: 试听音频 URL
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API_KEY
      description: 格式：`Bearer <API_KEY>`

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.