# 公共音色列表 API Documentation

> 列出平台公共音色及 voice_id，可直接用于语音合成（voice_type=public）。支持按性别、关键词筛选。查询不扣费。

## Overview

This document describes how to call the **公共音色列表** API.

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

## 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**: `GET|POST https://apis.xiaobao.ink/api/aihuman/public_voices`
- **Content-Type**: `application/json` (request body commonly `application/json` or `application/x-www-form-urlencoded` for POST)
- **HTTP Method**: `GET / POST`
- **Note**: This endpoint accepts both GET query parameters and POST form/JSON body.

### Request Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `gender` | No | 可选 female\|male |
| `keyword` | No | 可选，按名称/风格/描述/标签模糊筛选 |
| `voice_id` | No | 可选，精确取某一音色 |

> **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/public_voices?key=你的密钥
```

## Details

## 接口说明：

返回平台维护的**公共音色**列表。每条含 `voice_id` 与描述字段，可直接作为 [语音合成](/doc/10) 的 `voice_id`（并设置 `voice_type=public`）。无需先做声音克隆即可配音。查询不扣费。

**请求方法：**支持 `GET` 与 `POST`。

后续可继续在目录中追加新音色；接入方以本接口返回为准。文档页顶部会动态展示当前公共音色目录（含试听）。

## 请求HEADER：

| 名称 | 值 |
| --- | --- |
| Content-Type | application/json 或 application/x-www-form-urlencoded（POST 时） |

## 请求参数说明：

| 名称 | 必填 | 类型 | 示例值 | 说明 |
| --- | --- | --- | --- | --- |
| gender | 否 | string | female | 按性别筛选：female / male |
| keyword | 否 | string | 悠悠 | 按名称、风格、描述、标签模糊筛选；亦可用参数名 q |
| voice_id | 否 | string | c5469fea1ca07847 | 精确取某一音色；亦可用参数名 id |

## 返回参数说明：

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| total | int | 列表条数 |
| list | array | 音色列表 |
| list[].voice_id | string | 音色 ID，传给 TTS |
| list[].name | string | 展示名称 |
| list[].gender | string | female / male |
| list[].lang | string | 语言，如 zh-cn |
| list[].style | string | 风格简述 |
| list[].description | string | 音色文字描述，便于选型 |
| list[].demo_url | string | 试听音频公网地址 |
| list[].tags | array | 标签 |
| usage | object | 使用提示（tts 地址等） |

## Response Example

```json
{
    "code": 200,
    "msg": "查询成功",
    "data": {
        "total": 5,
        "list": [
            {
                "voice_id": "c5469fea1ca07847",
                "name": "悠悠",
                "gender": "female",
                "lang": "zh-cn",
                "style": "女声·亲切",
                "description": "亲切自然的女声，语气柔和、吐字清晰，适合日常口播、产品介绍与短视频旁白。",
                "demo_url": "https://wikixiaobao.oss-accelerate.aliyuncs.com/uploads/digital_human/voice/20260509/2ff8775941da6a8be38a7028cf0382ce_1778295258.wav",
                "tags": [
                    "女",
                    "亲切",
                    "口播"
                ],
                "sort": 10
            },
            {
                "voice_id": "c5469fea5f76c4bf",
                "name": "磁性男士",
                "gender": "male",
                "lang": "zh-cn",
                "style": "男声·磁性",
                "description": "低沉有磁性的男声，质感稳重，适合品牌解说、广告配音与专业旁白。",
                "demo_url": "https://wikixiaobao.oss-accelerate.aliyuncs.com/uploads/digital_human/voice/20260509/975294e26d8c2894c42f458449c9ee02_1778296333.wav",
                "tags": [
                    "男",
                    "磁性",
                    "解说"
                ],
                "sort": 20
            },
            {
                "voice_id": "c5469fea610b1ba8",
                "name": "故事解读",
                "gender": "male",
                "lang": "zh-cn",
                "style": "男声·叙事",
                "description": "沉稳叙事男声，节奏适中、适合讲故事，可用于故事讲述、知识解读与长文朗读。",
                "demo_url": "https://wikixiaobao.oss-accelerate.aliyuncs.com/uploads/digital_human/voice/20260509/6b28c94190242046e31c2d43534d69e5_1778296353.wav",
                "tags": [
                    "男",
                    "故事",
                    "解读"
                ],
                "sort": 30
            },
            {
                "voice_id": "c5469fea627d2d6c",
                "name": "阳光男生",
                "gender": "male",
                "lang": "zh-cn",
                "style": "男声·阳光",
                "description": "清爽阳光的男声，语气轻松有活力，适合生活类口播、青春向短视频与日常分享。",
                "demo_url": "https://wikixiaobao.oss-accelerate.aliyuncs.com/uploads/digital_human/voice/20260509/4db777fd7fb9bee0010cb6cf32ab769e_1778296375.wav",
                "tags": [
                    "男",
                    "阳光",
                    "口播"
                ],
                "sort": 40
            },
            {
                "voice_id": "c5469fea64412d85",
                "name": "热情娜娜",
                "gender": "female",
                "lang": "zh-cn",
                "style": "女声·热情",
                "description": "热情活泼的女声，感染力强，适合带货口播、促销介绍与活力向内容。",
                "demo_url": "https://wikixiaobao.oss-accelerate.aliyuncs.com/uploads/digital_human/voice/20260509/f443f03396f943c6d93a767baa41e5aa_1778296406.wav",
                "tags": [
                    "女",
                    "热情",
                    "口播"
                ],
                "sort": 50
            }
        ],
        "usage": {
            "tts": "https://apis.xiaobao.ink/api/aihuman/tts",
            "hint": "将 list[].voice_id 作为 tts 的 voice_id，并设置 voice_type=public"
        }
    }
}
```

## Error Codes

| HTTP 响应状态码 | 说明 |
| --- | --- |
| 200 | 查询成功 |
| 400 | 接口未开启或未入库 |
| 401 | 认证失败，请检查 key |

## Usage Flow

1. Obtain your API Key from the console
2. Call the endpoint with `key` and required parameters
3. Parse the JSON (or binary) response according to the examples above

---

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