API_DOCUMENTATION.md

# Genie-TTS API 文档

> **Base URL**: `https://simler-genie-tts-testing.hf.space`

---

## 接口概览

| 端点 | 方法 | 描述 |
|------|------|------|
| `/health` | GET | 健康检查，返回已加载模型列表 |
| `/load_model` | POST | 动态加载新模型 |
| `/tts` | POST | 文本转语音（使用已加载模型） |
| `/upload_and_tts` | POST | 上传参考音频并生成语音 |

---

## 1. 健康检查

```
GET /health
```

**响应示例**:
```json
{
  "status": "ok",
  "models": ["Base", "god", "mzm"]
}
```

---

## 2. 加载模型

```
POST /load_model
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `character_name` | string | ✅ | 角色名称 |
| `model_path` | string | ✅ | 模型路径（相对于 `/app`） |
| `language` | string | ❌ | 语言，默认 `zh` |

---

## 3. 文本转语音

```
POST /tts
```

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `text` | string | ✅ | - | 要合成的文本 |
| `character_name` | string | ❌ | `Base` | 使用的角色模型 |
| `prompt_text` | string | ❌ | - | 覆盖参考音频文本 |
| `prompt_lang` | string | ❌ | `zh` | 参考音频语言 |
| `text_lang` | string | ❌ | - | 目标文本语言（跨语言合成时使用） |
| `speed` | float | ❌ | `1.0` | 语速调节（0.5-2.0） |
| `fragment_interval` | float | ❌ | `0.3` | 句子间隔时长（秒） |
| `fade_duration` | float | ❌ | `0.0` | 淡入淡出时长（秒） |

**响应**: `audio/wav` 音频流

---

## 4. 上传参考音频并生成

```
POST /upload_and_tts
```

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `file` | file | ✅ | - | 参考音频文件（WAV） |
| `prompt_text` | string | ✅ | - | 参考音频对应的文本 |
| `text` | string | ✅ | - | 要合成的文本 |
| `character_name` | string | ❌ | `Default` | 角色名称 |
| `language` | string | ❌ | `zh` | 语言 |
| `text_lang` | string | ❌ | - | 目标文本语言 |
| `speed` | float | ❌ | `1.0` | 语速调节 |
| `fragment_interval` | float | ❌ | `0.3` | 句子间隔时长（秒） |
| `fade_duration` | float | ❌ | `0.0` | 淡入淡出时长（秒） |

---

## 参数详解

### `speed` - 语速调节
- 范围：`0.5` ~ `2.0`
- `< 1.0`：语速变慢
- `> 1.0`：语速变快

### `fragment_interval` - 句子间隔
- 多句文本时，句子之间的静音间隔
- 推荐值：`0.3` ~ `0.5` 秒

### `fade_duration` - 淡入淡出
- 每个句子开头淡入、结尾淡出
- 用于平滑过渡，避免硬切
- 推荐值：`0.05` ~ `0.15` 秒

### `text_lang` - 跨语言合成
- 当参考音频语言与目标文本语言不同时使用
- 示例：日语参考音频 + 中文文本 → `prompt_lang=jp`, `text_lang=zh`

---

## 使用示例

### Python 请求示例

```python
import requests

response = requests.post(
    "https://simler-genie-tts-testing.hf.space/tts",
    data={
        "text": "你好，这是一段测试语音。",
        "character_name": "god",
        "speed": 1.0,
        "fragment_interval": 0.3,
        "fade_duration": 0.1
    }
)

with open("output.wav", "wb") as f:
    f.write(response.content)
```

### 跨语言合成示例

```python
response = requests.post(
    "https://simler-genie-tts-testing.hf.space/tts",
    data={
        "text": "大家好，我是若叶睦。",
        "character_name": "mzm",
        "prompt_lang": "jp",   # 参考音频是日语
        "text_lang": "zh"      # 目标文本是中文
    }
)
```

---

## 注意事项

1. **参考音频文本必须准确**：如果 `prompt_text` 与参考音频内容不匹配，会导致参考音频泄露到输出中
2. **跨语言合成**：需要同时指定 `prompt_lang` 和 `text_lang`
3. **模型需要预加载**：使用 `/tts` 前，确保模型已通过 `/load_model` 加载