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

响应示例:

{
  "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 请求示例

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)

跨语言合成示例

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 加载