# 声音资源 (Voice Resources) API

声音资源 API 用于管理 TTS 语音合成的声音配置。

## 基础信息

| 项目 | 值 |
|------|-----|
| Base URL | `/api/v1/voices` |
| 认证方式 | Bearer Token (预留) |

---

## 数据模型

### Voice

```typescript
interface Voice {
  id: string;           // 声音ID
  user_id?: number;      // 所属用户ID (系统声音可为null)
  name: string;         // 声音名称
  vendor: string;       // 供应商: "Ali" | "Volcano" | "Minimax" | "硅基流动"
  gender: string;       // 性别: "Male" | "Female"
  language: string;     // 语言: "zh" | "en"
  description: string;  // 描述
  // 扩展参数 (voice_params)
  model?: string;        // 语音模型标识
  voice_key?: string;   // 厂商voice_key
  speed?: number;       // 默认语速 (0.5-2.0)
  gain?: number;        // 音量增益 (-10~10 dB)
  pitch?: number;       // 音调调整
  enabled: boolean;
  is_system: boolean;   // 是否系统预设
  created_at: string;
}
```

### VoiceParams

```typescript
interface VoiceParams {
  speed: number;       // 语速 0.5-2.0
  gain: number;        // 音量增益 -10~10 dB
  pitch: number;       // 音调调整
```

---

## API 端点

### 1. 获取声音列表

```http
GET /api/v1/voices
```

**Query Parameters:**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| vendor | string | 否 | 过滤供应商 |
| gender | string | 否 | 过滤性别: "Male" \| "Female" |
| language | string | 否 | 过滤语言: "zh" \| "en" |
| is_system | boolean | 否 | 是否系统预设 |

**Response:**

```json
{
  "total": 15,
  "list": [
    {
      "id": "voice_001",
      "user_id": null,
      "name": "晓云",
      "vendor": "Ali",
      "gender": "Female",
      "language": "zh",
      "description": "温柔女声，适合客服场景",
      "model": "paimeng",
      "voice_key": "xiaoyun",
      "speed": 1.0,
      "gain": 0,
      "pitch": 0,
      "enabled": true,
      "is_system": true,
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "voice_002",
      "user_id": null,
      "name": "Kevin",
      "vendor": "Volcano",
      "gender": "Male",
      "language": "en",
      "description": "专业男声，适合商务场景",
      "model": "知心",
      "voice_key": "kevin_male",
      "speed": 1.0,
      "gain": 0,
      "enabled": true,
      "is_system": true
    },
    {
      "id": "voice_003",
      "user_id": 1,
      "name": "定制客服女声",
      "vendor": "Minimax",
      "gender": "Female",
      "language": "zh",
      "description": "定制的客服女声",
      "model": "abcs",
      "voice_key": "custom_voice_001",
      "speed": 1.1,
      "gain": 2,
      "enabled": true,
      "is_system": false
    }
  ]
}
```

---

### 2. 获取单个声音详情

```http
GET /api/v1/voices/{id}
```

**Response:**

```json
{
  "id": "voice_001",
  "user_id": null,
  "name": "晓云",
  "vendor": "Ali",
  "gender": "Female",
  "language": "zh",
  "description": "温柔女声，适合客服场景",
  "model": "paimeng",
  "voice_key": "xiaoyun",
  "speed": 1.0,
  "gain": 0,
  "pitch": 0,
  "enabled": true,
  "is_system": true,
  "created_at": "2024-01-15T10:30:00Z"
}
```

---

### 3. 创建声音配置

```http
POST /api/v1/voices
```

**Request Body:**

```json
{
  "name": "定制客服女声",
  "vendor": "Minimax",
  "gender": "Female",
  "language": "zh",
  "description": "定制的客服女声",
  "model": "abcs",
  "voice_key": "custom_voice_001",
  "speed": 1.1,
  "gain": 2,
  "pitch": 0,
  "enabled": true
}
```

**Fields 说明:**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | 声音名称 |
| vendor | string | 是 | 供应商: "Ali" \| "Volcano" \| "Minimax" \| "OpenAI Compatible" \| "DashScope" |
| gender | string | 是 | 性别: "Male" \| "Female" |
| language | string | 是 | 语言: "zh" \| "en" |
| description | string | 否 | 描述信息 |
| model | string | 否 | 厂商语音模型标识 (可选，部分供应商有默认值) |
| voice_key | string | 否 | 厂商 voice_key (可选，部分供应商有默认值) |
| api_key | string | 否 | 供应商 API Key (可选，也可通过环境变量配置) |
| base_url | string | 否 | API Base URL (可选，部分供应商有默认值) |
| speed | number | 否 | 默认语速 (0.5-2.0)，默认 1.0 |
| gain | number | 否 | 音量增益 (-10~10 dB)，默认 0 |
| pitch | number | 否 | 音调调整，默认 0 |
| enabled | boolean | 否 | 是否启用，默认 true |

---

### 4. 更新声音配置

```http
PUT /api/v1/voices/{id}
```

**Request Body:** (部分更新)

```json
{
  "name": "优化版客服女声",
  "speed": 1.15,
  "gain": 1
}
```

---

### 5. 删除声音配置

```http
DELETE /api/v1/voices/{id}
```

**注意:** 系统预设声音不可删除

---

### 6. 预览声音

```http
POST /api/v1/voices/{id}/preview
```

**Request Body:**

```json
{
  "text": "您好，请问有什么可以帮助您？",
  "speed": 1.0,
  "gain": 0
}
```

**Response:**

```json
{
  "success": true,
  "audio_url": "data:audio/wav;base64,UklGRi...",
  "duration_ms": 2500,
  "error": null
}
```

**注意:** `audio_url` 返回 Base64 编码的音频数据 (data URI 格式)，可直接在浏览器中播放或解码保存为音频文件。

---

### 7. 获取供应商声音列表

```http
GET /api/v1/voices/vendors/{vendor}/available
```

**Path Parameters:**

| 参数 | 类型 | 说明 |
|------|------|------|
| vendor | string | 供应商名称 |

**Response:**

```json
{
  "vendor": "Ali",
  "voices": [
    {
      "model": "paimeng",
      "voice_key": "xiaoyun",
      "name": "晓云",
      "gender": "Female",
      "language": "zh"
    },
    {
      "model": "paimeng",
      "voice_key": "guang",
      "name": "广志",
      "gender": "Male",
      "language": "zh"
    },
    {
      "model": "maimeng",
      "voice_key": "sijia",
      "name": "思佳",
      "gender": "Female",
      "language": "zh"
    }
  ]
}
```

---

## 推荐的 Schema 定义

```python
# ============ Voice ============
class VoiceGender(str, Enum):
    MALE = "Male"
    FEMALE = "Female"

class VoiceBase(BaseModel):
    name: str
    vendor: str
    gender: str
    language: str  # "zh" | "en"
    description: str = ""
    model: str
    voice_key: str
    speed: float = 1.0
    gain: int = 0
    pitch: int = 0
    enabled: bool = True

class VoiceCreate(VoiceBase):
    pass

class VoiceUpdate(BaseModel):
    name: Optional[str] = None
    description: Optional[str] = None
    speed: Optional[float] = None
    gain: Optional[int] = None
    pitch: Optional[int] = None
    enabled: Optional[bool] = None

class VoiceOut(VoiceBase):
    id: str
    user_id: Optional[int] = None
    is_system: bool = False
    created_at: datetime

    class Config:
        from_attributes = True

class VoicePreviewRequest(BaseModel):
    text: str
    speed: Optional[float] = None
    gain: Optional[int] = None
    pitch: Optional[int] = None

class VoicePreviewResponse(BaseModel):
    success: bool
    audio_url: Optional[str] = None
    duration_ms: Optional[int] = None
    error: Optional[str] = None
```

---

## 供应商声音示例

### 阿里云

| voice_key | name | gender | language | description |
|-----------|------|--------|----------|-------------|
| xiaoyun | 晓云 | Female | zh | 温柔女声 |
| guang | 广志 | Male | zh | 磁性男声 |
| sijia | 思佳 | Female | zh | 知性女声 |
| yunxiang | 云翔 | Male | zh | 活力男声 |

### 火山引擎

| voice_key | name | gender | language | description |
|-----------|------|--------|----------|-------------|
| doubao | 豆包 | Female | zh | 活泼女声 |
| kevin | Kevin | Male | en | 专业男声 |
| lucy | Lucy | Female | en | 甜美女声 |

### MiniMax

| voice_key | name | gender | language | description |
|-----------|------|--------|----------|-------------|
| abby | Abby | Female | en | 自然女声 |
| john | John | Male | en | 成熟男声 |