OpenAI-Edge-TTS部署&API调用

引言

OpenAI-Edge-TTS 不仅仅是一个 Python 库，它还提供了一个 API 服务，允许用户通过 HTTP 请求来使用 Microsoft Edge 的 TTS 功能，并将其请求格式转换为OpenAI TTS通用格式，这使得它可以作为一个独立的微服务部署，或者集成到更大的系统中，比如听书或播客。

部署方式

1. Docker 部署 (推荐): 使用 Docker 和 Docker Compose 可以轻松地创建和管理容器化的环境，简化了环境配置和依赖管理。
2. Python 直接运行: 适合不想使用 Docker，或者需要进行本地开发和调试的用户。

Docker 部署详细步骤

1. 前提条件 (Prerequisites):

   • Docker: 需要安装 Docker Engine 和 Docker Compose。
     • Docker Engine：用于构建和运行 Docker 镜像。
     • Docker Compose：用于定义和管理多容器 Docker 应用程序。
     • 确保已安装 docker compose (注意不是 docker-compose).

2. 安装 (Installation):

   • 克隆仓库:

     git clone https://github.com/travisvn/openai-edge-tts.git
     cd openai-edge-tts
     

   • 环境变量配置:

     • 在项目根目录下创建一个名为 .env 的文件。
     • 将以下内容复制到 .env 文件中，并根据需要进行修改：

       API_KEY=your_api_key_here  # (可选) 设置 API 密钥，用于访问控制
       PORT=5050                # API 服务监听的端口，默认为 5050
       DEFAULT_VOICE=en-US-AvaNeural  # 默认语音
       DEFAULT_RESPONSE_FORMAT=mp3  # 默认响应格式
       DEFAULT_SPEED=1.0            # 默认语速
       DEFAULT_LANGUAGE=en-US         # 默认语言.
       
       REQUIRE_API_KEY=True        # 是否需要 API 密钥才能访问, True 为必须.
       REMOVE_FILTER=False          # 是否移除过滤。
       EXPAND_API=True              # 是否扩展 API。
       

     • 或者，可以直接复制 .env.example 文件并重命名为 .env：

       cp .env.example .env
       

     • 环境变量简要说明:
       • API_KEY: 如果设置了 REQUIRE_API_KEY=True，则调用时客户端需要提供API密钥才能访问 API。
       • PORT: API 服务监听的端口。
       • DEFAULT_VOICE, DEFAULT_RESPONSE_FORMAT, DEFAULT_SPEED: 这些是 API 的默认设置，如果客户端在请求中没有特别指定，就使用默认值（详细参数列在文末）。

   • 使用 Docker Compose 运行 (推荐):

     • 构建并启动服务:

       docker compose up --build
       

       • --build: 在启动服务之前，强制重新构建 Docker 镜像。这在您修改了项目代码或 Dockerfile 后非常有用。

     • 后台运行:

       docker compose up -d
       

       -d: 以“分离模式”运行 Docker Compose，服务将在后台运行。

   • 直接使用 Docker 运行 (备选方案):

     • 构建镜像

     docker build -t openai-edge-tts .
     

     • 运行容器：

        docker run -p 5050:5050 --env-file .env openai-edge-tts
       

       • -p 5050:5050: 将容器的 5050 端口映射到主机的 5050 端口。
       • --env-file .env: 指定包含环境变量的文件。

     • 后台运行：

       docker run -d -p 5050:5050 --env-file .env openai-edge-tts
       

3. 访问 API:

   • 详细调用会在第四部分阐明， 服务启动后，可以通过 http://localhost:5050 访问 API (如果是云服务器，需要开放端口后把请求地址换成主机地址)

Python 运行详细步骤

1. 克隆仓库:

   git clone https://github.com/travisvn/openai-edge-tts.git
   cd openai-edge-tts
   

2. 设置虚拟环境 :

   • 创建虚拟环境：

     # macOS/Linux
     python3 -m venv venv
     # Windows
     python -m venv venv
     

   • 激活虚拟环境：

     # macOS/Linux
     source venv/bin/activate
     # Windows
     venv\Scripts\activate
     

   • 使用虚拟环境可以隔离项目依赖，避免与其他 Python 项目冲突。

3. 安装依赖:

   pip install -r requirements.txt
   

4. 配置环境变量:

   • 与 Docker 部署方式相同，创建 .env 文件并设置环境变量。

5. 运行服务:

   python app/server.py
   

有两种调用 API 请求的方式：通过命令行直接运行，或者通过工具发送请求。

API调用

方式 1：使用命令行运行 curl

打开命令行终端：

• Windows: 按 Win + R，输入 cmd 或 powershell。
• macOS/Linux: 打开终端应用。

运行 curl 命令：

• 请求示例：

curl -X POST http://localhost:5050/v1/audio/speech \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key_here" \
  -d '{
    "input": "Hello, I am your AI assistant! What can I help you?",
    "voice": "alloy",
    "response_format": "mp3",
    "speed": 1.1
  }' \
  --output speech.mp3

• 替换示例中的 your_api_key_here 为 .env 中设置的 API Key。
• 复制代码段并粘贴到终端中。
• 按回车运行。
• 如果请求成功，语音文件将保存为 speech.mp3，文件会出现在当前工作目录下。

输出如下：

方式 2：使用 Postman（或其他 API 开发工具）

如果使用 curl 太繁琐，可以使用 GUI 工具（例如 Postman）来发送请求。

1. 安装 Postman：
   • 下载地址：https://www.postman.com/
2. 创建请求：
   • 打开 Postman，点击 New Request。
   • 方法：选择 POST。
   • URL：输入 http://localhost:5050/v1/audio/speech。
3. 设置 Headers：
   • 添加 Header：Content-Type: application/json
   • 添加 Header：Authorization: Bearer your_api_key_here
4. 设置 Body：
   • 复制以下 JSON 内容到 Body 的 raw 模式中（选择 Text -> JSON）：

     {
       "input": "Hello, I am your AI assistant!",
       "voice": "alloy",
       "response_format": "mp3",
       "speed": 1.1
     }

5. 发送请求：
   • 点击 Send 按钮测试。
6. 保存文件：
   • 如果请求成功，Postman 会返回一个 MP3 文件。点击 Save Response，将该文件保存到本地。

常见问题

主要是客户端请求格式不对，虽然POST后能GET到mp3文件，但是播放时会报错，查看源码会得到以下内容:

<!doctype html>
<html lang=en>
<title>400 Bad Request</title>
<h1>Bad Request</h1>
<p>The browser (or proxy) sent a request that this server could not understand.</p>

排查&解决流程

1. JSON 的格式问题

curl -d 参数中使用了一个复杂的 JSON 数据，其中包含换行符（\n）。如果没有正确地转义（或处理多行 JSON），这会导致格式问题。换行符可能会破坏 JSON 的结构，让服务器无法理解。

解决方法 1：将 JSON 压缩为单一行
将你的 JSON 数据改为单行，避免多行和换行符的影响：

curl -X POST http://localhost:5050/v1/audio/speech \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 273299033lee" \
  -d '{"input": "He came across the street, finally, muffled in his ancient overcoat, shapeless felt hat pulled down over his bald head, looking more like an energetic gnome than an eminent psychiatrist. His offices were nearby.", "voice": "alloy", "response_format": "mp3", "speed": 1.1}' \
  --output speechthree.mp3

解决方法 2：使用文件传递 JSON 数据
将 JSON 数据保存到一个文件中，然后引用文件路径提升健壮性：

1. 创建一个文件，例如 input.json，并将 JSON 内容保存到文件中：

   {
     "input": "He came across the street, finally, muffled in his ancient overcoat, shapeless felt hat pulled down over his bald head, looking more like an energetic gnome than an eminent psychiatrist. His offices were nearby.",
     "voice": "alloy",
     "response_format": "mp3",
     "speed": 1.1
   }
   

2. 然后在 curl 请求中使用 -d @input.json 来读取文件作为请求体：

   curl -X POST http://localhost:5050/v1/audio/speech \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer 273299033lee" \
     -d @input.json \
     --output speechthree.mp3
   

2. 内容长度超出了 API 限制

有些语音合成 API 对 input 文本有字符长度限制。如果你的输入文本超出了限制（例如 200 字符或 500 字符等），可能直接导致请求失败。

解决方法：
你可以尝试以下方法：

1. 缩短输入文本：

   curl -X POST http://localhost:5050/v1/audio/speech \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer 273299033lee" \
     -d '{"input": "He came across the street, finally.", "voice": "alloy", "response_format": "mp3", "speed": 1.1}' \
     --output speechthree.mp3
   

   如果短文本能返回结果，则说明确实是长度问题。

2. 根据 API 文档分割输入：
   如果需要处理长文本，请调研 API 文档，看看是否支持分段语音合成。如果支持，你需要手动分段，并循环多次调用 API 进行合成。

3. Authorization Token（API Key）无效

客户端提供的 Bearer Token 无效，API Key失效了或者格式不对。

解决方法：

1. 确认你的 API Key 是真实且有效的。
2. 确保它以 Authorization: Bearer XXXX 格式传递，而且正确。

4. API 服务端点路径错误

请求的 URL 一般情况下是 http://localhost:5050/v1/audio/speech ，但是服务端端口如果不是默认的5050，就需要修改，另外请求地址在本机就是 localhost，在云机就是云机的地址。最后API的路由是标准的 OpenAI TTS的路由 /v1/audio/speech

5. 服务器可能不支持多参数 Header

某些服务器对 HTTP 请求头过于敏感。例如：

• Authorization 可能不被正确识别。
• Header 格式错误。

附录

edge-tts 语音角色列表