Metadata-Version: 2.4
Name: omnivoice-server-api
Version: 0.0.1
Summary: A Python async SDK that wraps the OmniVoice TTS server API into a clean, type-safe interface.
Author-email: Jerry <wujr24@m.fudan.edu.cn>
License: MIT
Project-URL: Homepage, https://github.com/Jerry-Wu-GitHub/omnivoice-server-api
Project-URL: Repository, https://github.com/Jerry-Wu-GitHub/omnivoice-server-api.git
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiofiles
Requires-Dist: httpx
Requires-Dist: python-dotenv
Requires-Dist: yarl
Dynamic: license-file

# OmniVoice Server API Python SDK

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)

一个**异步**、**类型安全**的 Python SDK，用于调用 [omnivoice-server](https://github.com/Howard-Hou/OmniVoice) 的 OpenAI 兼容 TTS HTTP 服务。

它提供了直观的接口，覆盖语音合成、声音克隆、多角色脚本合成、声音配置管理与模型查询等功能，让您能以 Pythonic 的方式生成语音。

## ✨ 特性

- 🚀 **全异步** – 基于 `httpx.AsyncClient`，支持高并发请求。
- 📦 **类型安全** – 提供 `AudioFormat`、`ScriptOutputFormat`、`ScriptSegment` 等数据模型，配合 IDE 自动补全。
- 🎙️ **语音合成** – 支持普通合成（`create_speech`）、一次发音克隆（`create_speech_clone`）与多角色脚本合成（`create_script_audio`）。
- 🔑 **灵活认证** – 通过 `headers` 或自定义 `http_client` 注入 `Authorization` 头。
- 🛠️ **开箱即用** – 支持 `.env` 配置，简洁的异步上下文管理。

## 📦 安装

```bash
pip install omnivoice-server-api
```

或直接从源码安装：

```bash
git clone https://github.com/Jerry-Wu-GitHub/omnivoice-server-api.git
cd omnivoice-server-api
pip install -e .
```

## 🚀 快速开始

### 1. 配置服务地址

默认使用 ModelScope 推理地址。若需要自定义，可在项目根目录创建 `.env` 文件：

```env
OMNIVOICE_BASE_URL=https://studio-jerrywumodelscope-omnivoice-server.api-inference.modelscope.net
```

### 2. 基础用法

```python
import asyncio
from omnivoice_server_api import OmniVoiceClient

async def main():
    async with OmniVoiceClient() as client:
        # 合成语音
        audio = await client.create_speech(
            "你好，欢迎使用 OmniVoice 语音合成服务。",
            voice="auto",
            response_format="mp3",
        )
        with open("output.mp3", "wb") as f:
            f.write(audio)

        # 列出可用声音
        voices = await client.list_voices()
        print(voices)

if __name__ == "__main__":
    asyncio.run(main())
```

### 3. 认证（如服务需要）

通过 `headers` 注入 `Authorization` 头：

```python
from omnivoice_server_api import OmniVoiceClient

client = OmniVoiceClient(headers={"Authorization": "Bearer <your_token>"})
```

## 📖 API 概览

SDK 的所有功能通过 `OmniVoiceClient` 提供：

| 方法                    | 说明                       | 对应接口                            |
| ----------------------- | -------------------------- | ----------------------------------- |
| `create_speech()`       | 文本合成语音               | `POST /v1/audio/speech`             |
| `create_speech_clone()` | 一次发音克隆               | `POST /v1/audio/speech/clone`       |
| `create_script_audio()` | 多角色脚本合成             | `POST /v1/audio/script`             |
| `list_voices()`         | 列出可用声音               | `GET /v1/voices`                    |
| `create_profile()`      | 保存声音克隆配置           | `POST /v1/voices/profiles`          |
| `get_profile()`         | 获取声音克隆配置           | `GET /v1/voices/profiles/{id}`      |
| `update_profile()`      | 更新声音克隆配置           | `PATCH /v1/voices/profiles/{id}`    |
| `delete_profile()`      | 删除声音克隆配置           | `DELETE /v1/voices/profiles/{id}`   |
| `list_models()`         | 列出模型                   | `GET /v1/models`                    |
| `get_model()`           | 获取模型                   | `GET /v1/models/{id}`               |
| `health()`              | 就绪检查                   | `GET /health`                       |
| `metrics()`             | 请求指标与内存使用         | `GET /metrics`                      |

### 详细示例：一次发音克隆

```python
async def clone_example(client):
    audio = await client.create_speech_clone(
        "这是使用克隆音色合成的语音。",
        ref_audio="reference.wav",      # 支持路径 / bytes / 文件对象
        ref_text="这是参考音频对应的文本。",
        response_format="wav",
    )
    with open("cloned.wav", "wb") as f:
        f.write(audio)
```

### 详细示例：多角色脚本合成

```python
from omnivoice_server_api import OmniVoiceClient, ScriptSegment, ScriptOutputFormat

async def script_example(client):
    script = [
        ScriptSegment(speaker="主持人", text="欢迎来到今天的节目。"),
        ScriptSegment(speaker="嘉宾", text="大家好，很高兴来到这里。"),
    ]
    audio = await client.create_script_audio(
        script,
        output_format=ScriptOutputFormat.SINGLE_TRACK,
        pause_between_speakers=0.8,
    )
    with open("script.wav", "wb") as f:
        f.write(audio)
```

### 详细示例：声音克隆配置管理

```python
async def profile_example(client):
    # 保存配置
    await client.create_profile("my_voice", ref_audio="reference.wav")

    # 查询配置
    profile = await client.get_profile("my_voice")
    print(profile)

    # 更新配置
    await client.update_profile("my_voice", ref_text="新的参考文本")

    # 删除配置
    await client.delete_profile("my_voice")
```

## 🧪 运行测试

项目包含测试用例，位于 `tests/` 目录，需要能访问服务端。运行：

```bash
python tests/main.py
```

## 📄 许可证

本项目使用 [MIT](LICENSE) 许可证。
