---

title: whisper.api emoji: 😶‍🌫️ colorFrom: purple colorTo: gray sdk: docker app_file: Dockerfile app_port: 7860

Whisper API 🎙️

一个开源、高性能、可自行部署的语音转文本转录 API，由 whisper.cpp 提供支持。

本项目提供与 Deepgram 兼容的接口（REST 和 WebSocket），便于集成到现有工作流中，同时确保数据完全归您所有。

---

核心特性

• 标准化 API：与 /v1/listen 端点无缝兼容。
• 高级转录功能：自定义词汇表（提示词）、音频裁剪（start/duration）以及说话人分离。
• 灵活格式：原生支持导出为 JSON、SRT 和 VTT 格式。
• 实时流式传输：通过 WebSocket 实现 16kHz PCM 的实时转录。
• 离线管理：简单的命令行工具，用于安全生成 API 密钥和管理模型。

---

文档

文档位于 docs/ 文件夹中（Astro Starlight 主题）。使用 Bun 在本地运行：

cd docs && bun install && bun run dev

文档内容包括：

• 快速入门与本地设置
• 身份验证与 API 密钥
• REST 和 WebSocket API 参考
• 代码示例
• 模型与部署指南
• 贡献流程

---

快速开始

1. 安装依赖

pip install -r requirements.txt
cp .env.example .env
chmod +x setup_whisper.sh
./setup_whisper.sh

2. 初始化数据库与密钥

python -m app.cli init
python -m app.cli create --name "MyAdminKey"

注意：仅用于本地测试时，可通过设置 ENABLE_TEST_TOKEN_ENDPOINT=true 在 Swagger 中启用 POST /v1/auth/test-token。默认情况下该功能是关闭的；请勿在生产环境中启用。

3. 启动服务器

uvicorn app.main:app --host 0.0.0.0 --port 7860

4. 使用 cURL 转录文件

curl -X POST 'http://localhost:7860/v1/listen' \
  -H "Authorization: Token <YOUR_KEY>" \
  -H "Content-Type: audio/wav" \
  --data-binary @audio.wav

5. 使用 cURL 从 URL 转录

curl -X POST 'http://localhost:7860/v1/listen' \
  -H "Authorization: Token <YOUR_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/audio.mp3"}'

服务器会为您下载指定 URL 的音频文件，并具备 SSRF 防护机制（仅允许公开主机，有大小限制，默认不跟随重定向）。有关 MAX_AUDIO_DOWNLOAD_BYTES、AUDIO_URL_FOLLOW_REDIRECTS 等相关配置，请参阅 docs/ 或 .env.example 文件。

---

许可证与参考

MIT 许可证

• whisper.cpp
• OpenAI Whisper

作者: Ved Gupta

Whisper API 快速上手指南

Whisper API 是一个基于 whisper.cpp 构建的高性能、自托管语音转文字（STT）开源工具。它提供与 Deepgram 兼容的 REST 和 WebSocket 接口，支持离线运行、实时流式转录及多种格式导出，适合注重数据隐私的开发者和团队。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Linux / macOS / Windows (WSL2 推荐)
• Python 版本：Python 3.8 或更高版本
• 前置依赖：
  • pip (Python 包管理工具)
  • git (用于克隆代码库)
  • ffmpeg (部分音频处理可能需要，建议安装)
  • bun (仅当需要本地运行文档时可选)

国内加速建议： 如果遇到 pip install 下载缓慢，建议使用国内镜像源：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

安装步骤

1. 获取代码与安装依赖

克隆项目并安装 Python 依赖，同时初始化环境变量文件。

git clone <repository_url>
cd whisper.api
pip install -r requirements.txt
cp .env.example .env

2. 初始化模型与环境

运行设置脚本来下载必要的 Whisper 模型并完成环境配置。

chmod +x setup_whisper.sh
./setup_whisper.sh

3. 初始化数据库与生成密钥

使用内置 CLI 工具初始化数据库并创建管理员 API 密钥。

python -m app.cli init
python -m app.cli create --name "MyAdminKey"

执行成功后，终端将输出您的 API Key，请妥善保存。

注意：仅限本地测试环境，可在 .env 中设置 ENABLE_TEST_TOKEN_ENDPOINT=true 以启用 Swagger 中的测试令牌端点。生产环境严禁开启此选项。

4. 启动服务

使用 uvicorn 启动 API 服务器。

uvicorn app.main:app --host 0.0.0.0 --port 7860

服务默认运行在 http://localhost:7860。

基本使用

启动服务后，您可以通过 HTTP POST 请求进行语音转录。以下是两种最常用的场景：

场景一：转录本地音频文件

将本地音频文件（如 audio.wav）直接发送给 API。

curl -X POST 'http://localhost:7860/v1/listen' \
  -H "Authorization: Token <YOUR_KEY>" \
  -H "Content-Type: audio/wav" \
  --data-binary @audio.wav

请将 <YOUR_KEY> 替换为步骤 3 中生成的实际密钥。

场景二：转录网络音频 URL

让服务器直接抓取并转录公网可访问的音频链接（内置 SSRF 防护）。

curl -X POST 'http://localhost:7860/v1/listen' \
  -H "Authorization: Token <YOUR_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/audio.mp3"}'

返回结果：默认返回 JSON 格式的转录文本，包含时间戳和置信度等信息。您也可以通过请求头指定输出格式（如 SRT 或 VTT）。