README.md

---
title: Genie Tts
emoji: 😻
colorFrom: green
colorTo: pink
sdk: docker
pinned: false
---
---

## Genie TTS API 使用文档

### 1. 概述

本文档旨在指导开发者如何调用部署在 Hugging Face Spaces 上的 Genie TTS 服务。该服务允许您通过 API 请求，使用预加载的角色模型将文本转换为高质量的语音。

**API 基地址 (Base URL):**
```
https://clown145-genie-tts-t.hf.space
```

### 2. 核心使用流程

本 API 的核心工作流程分为两步，**每次语音合成都需要完整执行这两个步骤**：

1.  **设置参考音频 (`/set_reference_audio`)**: 为指定的角色设置一段参考音频和对应的文本。这一步是为了让模型能够克隆出参考音频中的情感和语调。
2.  **请求语音合成 (`/tts`)**: 发送你想要合成的文本，服务器将返回对应的原始音频数据流。

### 3. API 端点详解

#### 3.1 设置参考音频

此端点用于为即将进行的 TTS 任务设置声音克隆所需的参考音频。

*   **Endpoint**: `POST /set_reference_audio`
*   **Method**: `POST`
*   **描述**: 为指定角色设置参考音频及其文本。这是成功进行语音合成的**前提条件**。

*   **请求体 (Request Body)**: `JSON`
    ```json
    {
      "character_name": "aoi",
      "audio_path": "reference_audio/12b00400a02.ogg",
      "audio_text": "世界の外に電波発信してるの"
    }
    ```

*   **参数说明**:
    *   `character_name` (string, 必需): 你想要使用的角色名称。此名称必须与服务器启动时加载的某个角色匹配 (例如: "aoi", "kisaki", "may")。
    *   `audio_path` (string, 必需): 参考音频文件在 **Hugging Face 仓库中的相对路径**。服务器会在其下载的代码库中自动查找此文件。
    *   `audio_text` (string, 必需): 与参考音频文件内容完全匹配的文本。

*   **响应 (Response)**:
    *   **成功**:
        *   **状态码**: `200 OK`
        *   **内容**: `{"message": "Reference audio set successfully."}`
    *   **失败**:
        *   **状态码**: `404 Not Found` (如果角色未找到)

#### 3.2 请求语音合成

在设置好参考音频后，使用此端点来生成语音。

*   **Endpoint**: `POST /tts`
*   **Method**: `POST`
*   **描述**: 根据传入的文本，为当前设置了参考音频的角色生成语音，并以原始音频流的形式返回。

*   **请求体 (Request Body)**: `JSON`
    ```json
    {
      "character_name": "aoi",
      "text": "これからもし同じようなことがあっても",
      "split_sentence": true
    }
    ```

*   **参数说明**:
    *   `character_name` (string, 必需): 你想要使用的角色名称，必须与上一步中设置的角色一致。
    *   `text` (string, 必需): 你想要转换为语音的文本。
    *   `split_sentence` (boolean, 可选): 是否自动切分句子，默认为 `false`。推荐设置为 `true` 以获得更好的效果。

*   **响应 (Response)**:
    *   **成功**:
        *   **状态码**: `200 OK`
        *   **内容**: **纯原始音频数据流 (Raw PCM Audio Stream)**。
            *   **格式**: 单声道 (1 Channel)
            *   **采样率**: 32000 Hz
            *   **位深**: 16-bit PCM

    *   **失败**:
        *   **状态码**: `400 Bad Request` (如果未先设置参考音频)

### 4. 重要注意事项

*   **合成文本限制**: 只能合成日语。
*   **模型加载限制**: 当前服务配置为在启动时加载 **最多 3 个** 角色模型。请确保你请求的角色在预加载的名单中。
*   **音频输出格式**: `/tts` 接口返回的**不是一个 `.wav` 文件**，而是构成 `.wav` 文件的核心——原始 PCM 音频数据。客户端接收到数据后，需要自行使用 `wave` 等库来构建一个可播放的 `.wav` 文件。
*   **关于 `/load_character`**: 你可能在文档中看到过此接口，但在当前部署中，所有模型都在服务器启动时加载。**客户端无需也不应调用 `/load_character` 接口**。

### 5. 完整 Python 客户端示例

这是一个可以直接运行的 Python 脚本，展示了如何正确调用 API 并将返回的音频流保存为可播放的 `.wav` 文件。

```python
# client_example.py

import requests
import time
import os
import wave  # 导入 Python 标准的 wave 库，用于正确生成 .wav 文件

# --- API 配置 ---
BASE_URL = "https://clown145-genie-tts.hf.space"

# --- 音频参数 (必须与服务器输出匹配) ---
BYTES_PER_SAMPLE = 2  # 16-bit 音频
CHANNELS = 1          # 单声道
SAMPLE_RATE = 32000   # 32kHz 采样率

# --- 角色配置 ---
CHARACTERS = {
    "aoi": {
        "ref_audio": "reference_audio/12b00400a02.ogg",
        "ref_text": "世界の外に電波発信してるの"
    },
    "kisaki": {
        "ref_audio": "reference_audio/Kisaki_802.ogg",
        "ref_text": "ほら、ホタルもとても喜んでいます。ルリもそう呼んであげてくださいね。"
    },
    # 你可以在这里添加 'may' 或其他预加载的角色
}

def synthesize_speech_to_file(character_name, text_to_synthesize, output_path):
    """
    一个完整的调用流程：设置参考 -> 合成语音 -> 构建WAV文件。
    """
    if character_name not in CHARACTERS:
        print(f"错误：角色 '{character_name}' 未在配置中定义。")
        return

    print(f"\n--- 开始为角色 '{character_name}' 合成语音 ---")
    char_info = CHARACTERS[character_name]

    # 步骤 1: 动态设置参考音频
    print("[Client] 步骤 1: 正在设置参考音频...")
    ref_payload = {
        "character_name": character_name,
        "audio_path": char_info["ref_audio"],
        "audio_text": char_info["ref_text"]
    }
    try:
        response = requests.post(f"{BASE_URL}/set_reference_audio", json=ref_payload, timeout=60)
        response.raise_for_status()
        print(f"[Client] 角色 '{character_name}' 的参考音频设置成功。")
    except requests.exceptions.RequestException as e:
        print(f"[Client] 设置参考音频失败: {e}")
        return

    # 步骤 2: 请求 TTS 并将返回的原始音频流构建为 WAV 文件
    print(f"[Client] 步骤 2: 正在请求 TTS 并准备构建 WAV 文件到 {output_path}...")
    tts_payload = {
        "character_name": character_name,
        "text": text_to_synthesize,
        "split_sentence": True
    }

    try:
        with requests.post(f"{BASE_URL}/tts", json=tts_payload, stream=True, timeout=300) as response:
            response.raise_for_status()
            
            # 使用 wave 库来正确写入文件
            with wave.open(output_path, 'wb') as wf:
                # 这三行代码至关重要，它们会为原始音频数据写入正确的 WAV 文件头
                wf.setnchannels(CHANNELS)
                wf.setsampwidth(BYTES_PER_SAMPLE)
                wf.setframerate(SAMPLE_RATE)
                
                # 接收原始音频流数据块，并写入文件
                print("[Client] 正在接收音频流并写入 WAV 文件...")
                for chunk in response.iter_content(chunk_size=8192):
                    if chunk:
                        wf.writeframes(chunk)
            
            print(f"[Client] 🎉 恭喜！音频已成功构建并保存到: {output_path}")

    except requests.exceptions.RequestException as e:
        print(f"[Client] TTS 请求失败: {e}")
    except Exception as e:
        print(f"[Client] 保存文件时发生错误: {e}")

if __name__ == "__main__":
    # 确保输出文件夹存在
    if not os.path.exists("outputs"):
        os.makedirs("outputs")

    # --- 示例调用 ---
    print("\n" + "="*50)
    synthesize_speech_to_file(
        character_name="aoi", 
        text_to_synthesize="これは最初のテストです。",
        output_path="outputs/aoi_output.wav"
    )
    
    time.sleep(1) # 短暂间隔，避免请求过于频繁

    print("\n" + "="*50)
    synthesize_speech_to_file(
        character_name="kisaki", 
        text_to_synthesize="次の音声合成もお願いします。",
        output_path="outputs/kisaki_output.wav"
    )

```