# 声音克隆 API Documentation

> 声音克隆

## Overview

This document describes how to call the **声音克隆** API.

- **Model / path slug**: `aihuman/clonevoice`
- **Task type**: `async` (`sync` = synchronous, `async` = create task then poll / callback)
- **HTML docs**: `/doc/9`

## Authentication

All API requests require your platform API key as the query parameter `key`:

```
?key=YOUR_API_KEY
```

Get API Key:
1. Sign in to the console
2. Open [API Key Management](/user/key) and create or copy your key
3. Append `key=YOUR_API_KEY` to the request URL (or pass it in form/JSON when the endpoint accepts it)

---

## API Information

- **URL**: `POST https://apis.xiaobao.ink/api/aihuman/clonevoice`
- **Content-Type**: `application/json` (request body commonly `application/json` or `application/x-www-form-urlencoded` for POST)
- **HTTP Method**: `POST`

### Request Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `audio_url` | Yes | 原音频url |
| `name` | No | 可选 声音名称 |
| `lang` | No | 可选 语言，目前仅支持zh-cn、en 默认：zh-cn |
| `notify` | Yes | 回调地址，用于接收任务结果，任务结果数据会通过 POST 请求发送到该地址 |

> **Note**: `key` (API key) is required for authenticated calls even if omitted from the parameter list above.

### Request Example

```
https://apis.xiaobao.ink/api/aihuman/clonevoice?key=你的密钥
```

## Details

##
请求参数说明：

| 名称 | 必填 | 类型 | 示例值 | 说明 |
| --- | --- | --- | --- | --- |
| audio_url | 是 | string | https://xxx.mp3 | 原音频url  |
| name | 否 | string | UU的声音 | 声音名称 |
| lang | 否 | string | zh-cn | 语言，用哪种语言克隆的，仅能合成哪种语言的音频。 zh-cn：中文 en：英文 fr：法语 de：德语 ja：日语 ko：韩语 ru：俄语 pt：葡萄牙语 th：泰语 id：印尼语 vi：越南语 默认值: zh-cn |
| notify | 是 | string | http://xxx.com | 回调地址，用于接收任务结果，任务结果数据会通过 POST 请求发送到该地址 |

## 返回参数说明：

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| code | int | 状态码 |
| msg | string | 状态信息 |
| data | array | 请求结果数据集 （成功的时候有值） |
| - task_id | string | 任务id |
| exec_time | float | 执行耗时 |
| user_ip | string | 客户端IP |

**回调参数说明：**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| task_id | string | 任务id |
| status | int | 1成功 2失败 |
| voice_id | string | 音色id，仅成功时有 |
| demo_url | string | demo音频，仅成功时有值（文件仅短暂留存，请转存 |
| message | string | 失败原因，仅失败时有值 |

## Response Example

```json
{
    "code": 200,
    "data": {
        "task_id": "string"
    },
    "msg": "string"
}
```

## Error Codes

| Status / code | Description |
|---------------|-------------|
| 200 / success | Request successful |
| 400 | Invalid request parameters |
| 401 | Authentication failed, please check API Key |
| 402 | Insufficient account balance / points |
| 429 | Request rate limit exceeded |
| 500 | Internal server error |

## Usage Flow

1. **Create Task**: Call this API with your `key` and required parameters
2. **Get Task ID**: Read the task id from the response
3. **Wait for Results**: Use the notify/callback URL if provided, or poll the related query endpoint
4. **Get Results**: When the task succeeds, read result URLs / payload from the response

---

_Generated for AI / LLM consumption. Source of truth: `api_list` (same as HTML `/doc/{id}`)._