OmniVoice Server API Python SDK

一个异步、类型安全的 Python SDK，用于调用 omnivoice-server 的 OpenAI 兼容 TTS HTTP 服务。

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

✨ 特性

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

📦 安装

pip install omnivoice-server-api

或直接从源码安装：

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

🚀 快速开始

1. 配置服务地址

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

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

2. 基础用法

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 头：

from omnivoice_server_api import OmniVoiceClient

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

4. 并发限流

通过 max_concurrency 限制同时向服务器发送的请求数量，达到上限后后续请求会自动等待：

client = OmniVoiceClient(max_concurrency=4)  # 最多 4 个请求同时进行

📖 API 概览

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

详细示例：一次发音克隆

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)

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

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)

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

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/ 目录，需要能访问服务端。运行：

python tests/main.py

📄 许可证

本项目使用 MIT 许可证。