AngeVoice API 参考

HTTP、OpenAI-compatible、WebSocket、Voice Profile、批量导出与管理接口。

本文档是 AngeVoice v2.6.x 的 API 参考手册，涵盖 Studio Web UI、可复制示例页面 /api-docs、OpenAI 兼容 HTTP 合成、旧版 /api/tts 接口、模型切换、MOSS-TTS-Nano 参考音频克隆、WebSocket 流式合成、批量导出及可选管理接口。

调用地址

以下示例均使用：

BASE_URL=http://localhost:8000
WS_URL=ws://localhost:8000/ws/v1/tts

Docker 部署时只需替换端口号。远程 NAS 部署时把 localhost 换成 NAS 主机名或 IP，例如 http://192.168.1.2:8101。

文档页面

鉴权

当 KOKORO_API_KEY 为空时，本地可信部署无需 token 即可调用接口。当设置了 API key 后，HTTP 请求需要携带：

-H "Authorization: Bearer YOUR_TOKEN"

WebSocket 客户端可通过 Authorization 头或首条 JSON 消息传递 token：

{
  "text": "你好世界",
  "voice": "zm_010",
  "token": "YOUR_TOKEN"
}

内置 Studio Web UI 会在设置面板保存 Bearer Token，同时用于 HTTP 请求和 WebSocket 首包。

接口列表

/health status 字段

Docker 健康检查将 ok 和 idle 都视为可用状态。Docker 镜像的响应还包含 deployment_profile，用于区分 cpu、gpu 与 legacy-gpu 的实际测试路径；源码直跑默认显示 source。

产品模型 ID 与运行 Provider

运行 Provider 与产品名称分离。旧输入 moss-nano-cpu / moss-nano-cuda / moss-cpu / moss-gpu 继续解析到 canonical moss 并作为 provider hint，但不作为 Studio 展示名称；不提供公开 zipvoice-cpu / zipvoice-cuda ID。CPU/legacy-gpu 的 ZipVoice 使用 cpu_onnx_int8，标准 gpu 默认请求 cuda_pytorch 并在不可用时回退 cpu_onnx_int8。实际表现请以目标主机上的状态与诊断数据为准。

状态查询与发现

curl "$BASE_URL/health"
curl "$BASE_URL/stats"
curl "$BASE_URL/requests"
curl "$BASE_URL/v1/audio/formats"

查询音色列表（当前模型或指定模型）：

curl "$BASE_URL/v1/audio/voices"
curl "$BASE_URL/v1/audio/voices?model=moss"
curl "$BASE_URL/v1/audio/voices?detail=false"  # 精简响应，不含 voice_details

查询 TTS 能力（模型列表、可用格式、音色详情、前端提示）：

curl "$BASE_URL/v1/tts/capabilities"
curl "$BASE_URL/v1/tts/capabilities?include_voices=false"  # 不含音色详情

模型加载、切换与卸载：

curl "$BASE_URL/v1/models"
curl "$BASE_URL/v1/models/current"

curl -X POST "$BASE_URL/v1/models/moss/load" \
  -H "Authorization: Bearer YOUR_TOKEN"

curl -X POST "$BASE_URL/v1/models/switch" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"model":"moss","unload_previous":true}'

curl -X POST "$BASE_URL/v1/models/moss/unload" \
  -H "Authorization: Bearer YOUR_TOKEN"

设置 unload_previous=true 会在切换模型后释放旧引擎并清空音频缓存。GPU/NAS 部署推荐使用此选项。

OpenAI 兼容合成

接口地址：

POST /v1/audio/speech
Content-Type: application/json

请求参数：

Kokoro 示例：

curl -X POST "$BASE_URL/v1/audio/speech" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"model":"kokoro","input":"你好世界","voice":"zm_010","speed":1.0,"response_format":"wav"}' \
  --output kokoro.wav

MOSS 预设音色示例：

curl -X POST "$BASE_URL/v1/audio/speech" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"model":"moss","input":"派大星，我们一起去抓水母吧。","voice":"Junhao","response_format":"wav"}' \
  --output moss.wav

响应说明：

• 响应体为音频字节流
• Content-Type 为 audio/wav、audio/pcm、audio/mpeg、audio/ogg 或 audio/mp4，取决于 response_format
• 响应头包含 X-Request-ID
• 当 response_encoding=base64 时，响应为 JSON，包含 audio（裸 base64）、audio_base64（data URL）、sample_rate、channels 等字段

ZipVoice 保存音色示例：

curl -X POST "$BASE_URL/v1/audio/speech" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"model":"zipvoice","input":"这是已保存 ZipVoice 音色测试。","voice":"voice_001","response_format":"telegram_voice"}' \
  --output zipvoice.ogg

/v1/audio/speech 仅支持 JSON 格式。如需 MOSS/ZipVoice 参考音频克隆上传，请使用 /api/tts 的 multipart 方式。

旧版 /api/tts 接口

/api/tts 支持 JSON、query-string 和表单数据三种格式。当需要上传 MOSS/ZipVoice 参考音频进行克隆时，需使用此接口（multipart 上传不在 OpenAI 兼容 JSON 格式范围内）。

JSON 请求：

curl -X POST "$BASE_URL/api/tts" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"model":"kokoro","text":"你好世界","voice":"zm_010","format":"wav"}' \
  --output output.wav

Query-string 请求：

curl --get "$BASE_URL/api/tts" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --data-urlencode "text=你好世界" \
  --data-urlencode "voice=zm_010" \
  --data-urlencode "response_format=wav" \
  --output output.wav

Multipart 请求（不含克隆）：

curl -X POST "$BASE_URL/api/tts" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F model=kokoro \
  -F text="你好世界" \
  -F voice=zm_010 \
  -F response_format=wav \
  --output output.wav

MOSS 参考音频克隆

参考音频存放位置

MOSS 参考音频不是 Kokoro 音色文件，不要放到 models/models--hexgrad--Kokoro-82M-v1.1-zh/voices 目录。models/models--hexgrad--Kokoro-82M-v1.1-zh/voices 仅用于存放 Kokoro 的 .pt 音色文件。

参考音频建议：

• 时长 3-10 秒
• 单人说话
• 语音清晰，背景噪音低
• 避免过长的音乐或嘈杂片段

相关环境变量：

HTTP multipart 克隆

curl -X POST "$BASE_URL/api/tts" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F model=moss \
  -F text="这是参考音频克隆测试。" \
  -F voice=Junhao \
  -F response_format=wav \
  -F [email protected] \
  --output clone.wav

字段别名：

将 prompt_audio 上传到 kokoro 或其他不支持克隆的模型时，返回 400 当前模型不支持参考音频克隆。

Python HTTP 上传克隆示例

import requests

base_url = "http://localhost:8000"
headers = {"Authorization": "Bearer YOUR_TOKEN"}

with open("reference.wav", "rb") as audio:
    files = {"prompt_audio": ("reference.wav", audio, "audio/wav")}
    data = {
        "model": "moss",
        "text": "这是 Python 上传参考音频克隆测试。",
        "voice": "Junhao",
        "response_format": "wav",
    }
    resp = requests.post(f"{base_url}/api/tts", headers=headers, data=data, files=files)
    resp.raise_for_status()

with open("clone.wav", "wb") as out:
    out.write(resp.content)

服务端默认参考音频

如果所有 MOSS 克隆请求都使用同一段参考音频，可以将其挂载到容器内并设置 MOSS_PROMPT_AUDIO_PATH。

Docker Compose 示例：

volumes:
  - ../../prompts:/app/prompts:ro

environment:
  - MOSS_PROMPT_AUDIO_PATH=/app/prompts/reference.wav
  - MOSS_PROMPT_AUDIO_MAX_SECONDS=8
  - MOSS_PROMPT_CACHE_MAX_ITEMS=8

之后调用 /api/tts 时无需传 prompt_audio 字段：

curl -X POST "$BASE_URL/api/tts" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F model=moss \
  -F text="这次请求会使用服务端默认参考音频。" \
  -F voice=Junhao \
  -F response_format=wav \
  --output clone-default.wav

注意：这不会生成 Kokoro .pt 音色文件，只是为 MOSS 提供一条可复用的 prompt audio 路径。

ZipVoice 参考音频克隆

ZipVoice 可使用已保存 Voice Profile，也可通过 /api/tts multipart 临时上传参考音频与参考文本。prompt_text 必须是参考音频中真实朗读的自然语言文本；代码、URL、纯符号或日志会被拒绝。

临时参考音频示例：

curl -X POST "$BASE_URL/api/tts" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F model=zipvoice \
  -F text="这是 ZipVoice 临时参考音频克隆测试。" \
  -F voice=voice_001 \
  -F prompt_text="这是一段参考音频中实际朗读的文字。" \
  -F [email protected] \
  -F response_format=wav \
  --output zipvoice.wav

Telegram 语音格式示例，需启用 FFmpeg 转码：

curl -X POST "$BASE_URL/api/tts" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F model=zipvoice \
  -F text="这条语音将输出为 OGG Opus 格式。" \
  -F voice=voice_001 \
  -F response_format=telegram_voice \
  --output voice.ogg

WebSocket 流式合成

连接地址：

ws://localhost:8000/ws/v1/tts

首条 JSON 消息参数：

基础浏览器流式示例

const ws = new WebSocket("ws://localhost:8000/ws/v1/tts");

ws.onopen = () => {
  ws.send(JSON.stringify({
    model: "kokoro",
    text: "你好世界，这是一段流式合成测试。",
    voice: "zm_010",
    speed: 1.0,
    format: "pcm_s16le",
    binary: false,
    token: "YOUR_TOKEN"
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === "audio") {
    const pcmBytes = Uint8Array.from(atob(msg.data), (c) => c.charCodeAt(0));
    // 将 pcmBytes 送入 AudioWorklet、WebAudio buffer 或播放队列
  }
};

ws.send(JSON.stringify({ type: "cancel" }));

MOSS 克隆流式首包

{
  "model": "moss",
  "text": "这是参考音频克隆的流式测试。",
  "voice": "Junhao",
  "format": "pcm_s16le",
  "binary": false,
  "prompt_audio": {
    "filename": "reference.wav",
    "data": "<base64-or-data-url>"
  },
  "token": "YOUR_TOKEN"
}

为兼容旧版自定义客户端，也接受 prompt_audio_data、reference_audio_data 和 prompt_audio_filename 字段。

浏览器 FileReader 克隆流式

async function fileToDataUrl(file) {
  return await new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.onload = () => resolve(reader.result);
    reader.onerror = reject;
    reader.readAsDataURL(file);
  });
}

async function startMossCloneStream(file) {
  const promptData = await fileToDataUrl(file);
  const ws = new WebSocket("ws://localhost:8000/ws/v1/tts");

  ws.onopen = () => {
    ws.send(JSON.stringify({
      model: "moss",
      text: "这是网页端 MOSS 克隆流式测试。",
      voice: "Junhao",
      format: "pcm_s16le",
      binary: false,
      token: "YOUR_TOKEN",
      prompt_audio: {
        filename: file.name || "reference.wav",
        data: promptData
      }
    }));
  };

  ws.onmessage = (event) => {
    const msg = JSON.parse(event.data);
    if (msg.type === "audio") {
      const bytes = Uint8Array.from(atob(msg.data), c => c.charCodeAt(0));
      // bytes 为 PCM s16le 数据，送入 AudioWorklet/播放队列，或在客户端封装为 WAV
      console.log("audio chunk", bytes.byteLength);
    }
    if (msg.type === "done") ws.close();
    if (msg.type === "error" || msg.type === "segment_error") {
      console.error(msg.message);
    }
  };

  return ws;
}

Python WebSocket 克隆流式示例

import asyncio
import base64
import json
import websockets

async def main():
    with open("reference.wav", "rb") as f:
        prompt_b64 = base64.b64encode(f.read()).decode("ascii")

    async with websockets.connect("ws://localhost:8000/ws/v1/tts") as ws:
        await ws.send(json.dumps({
            "model": "moss",
            "text": "这是 Python WebSocket 克隆流式测试。",
            "voice": "Junhao",
            "format": "pcm_s16le",
            "binary": False,
            "token": "YOUR_TOKEN",
            "prompt_audio": {
                "filename": "reference.wav",
                "data": prompt_b64
            }
        }, ensure_ascii=False))

        with open("stream.pcm", "wb") as out:
            async for raw in ws:
                msg = json.loads(raw)
                if msg.get("type") == "audio":
                    out.write(base64.b64decode(msg["data"]))
                elif msg.get("type") in {"done", "cancelled"}:
                    break
                elif msg.get("type") in {"error", "segment_error"}:
                    raise RuntimeError(msg.get("message"))

asyncio.run(main())

上面的示例保存的是原始 PCM s16le 数据。如需直接得到 WAV 文件，可请求 format:"wav"，或根据返回的 sample_rate、channels 自行封装。

服务端消息类型：

二进制模式下，audio 消息的 JSON 部分不包含 data 字段，随后紧跟原始音频字节。JSON 模式始终在 data 字段中以 base64 编码传输。

批量 ZIP 合成

接口地址：

POST /v1/audio/batch
Content-Type: application/json

示例：

curl -X POST "$BASE_URL/v1/audio/batch" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "model":"kokoro",
    "voice":"zm_010",
    "speed":1.0,
    "response_format":"wav",
    "items":[
      {"text":"第一段","filename":"001"},
      {"text":"第二段","filename":"002","voice":"zf_001"},
      {"model":"moss","text":"第三段使用 MOSS。","voice":"Junhao","filename":"003"}
    ]
  }' \
  --output angevoice_batch.zip

响应为 application/zip 格式，包含：

• 每个成功项生成一个音频文件
• manifest.json 记录每项的状态、文件名、字节数或错误信息

批量项可单独覆盖 model、voice、speed 和 filename。批量接口不支持克隆上传，MOSS 参考音频克隆请使用 /api/tts multipart 方式。

取消请求

HTTP 请求返回的响应头包含 X-Request-ID，WebSocket 消息中包含 request_id。取消正在执行的请求：

curl -X POST "$BASE_URL/v1/audio/requests/REQUEST_ID/cancel" \
  -H "Authorization: Bearer YOUR_TOKEN"

WebSocket 客户端也可发送：

{"type":"stop"}

或：

{"type":"cancel"}

取消操作会阻止后续分段的推送。如果当前分段已进入同步推理阶段，通常会在该分段完成后停止。

管理后台与 Docker 管理接口

Docker 部署模板默认开启管理入口，并保留 admin / admin123 作为首次进入路径，以便普通用户查看 API Key。后台会提示默认凭据风险，公网暴露前必须在“安全 → 管理员账号与密码”修改；管理员用户名支持中文。服务只在持久化 credentials/admin-credentials.json 中保存修改后的 PBKDF2 哈希，升级必须保留此目录。

KOKORO_ADMIN_ENABLED=true
ANGEVOICE_ADMIN_USERNAME=admin
ANGEVOICE_ADMIN_PASSWORD='admin123'  # 首次进入默认值；公网暴露前必须修改
ANGEVOICE_CREDENTIALS_DIR=/app/credentials
ANGEVOICE_ADMIN_CREDENTIALS_FILE=/app/credentials/admin-credentials.json
ANGEVOICE_API_KEY_FILE=/app/credentials/.angevoice-api-key
ANGEVOICE_RUNTIME_CONFIG_FILE=/app/config/runtime-config.json

修改管理员凭据示例：

curl -X PUT "$BASE_URL/admin/api/security/credentials" \
  -u "admin:admin123" \
  -H 'Content-Type: application/json' \
  -d '{"username":"管理员01","password":"Replace-With-A-Strong-Password-2026"}'

下载诊断包：

curl "$BASE_URL/admin/api/diagnostics/bundle" \
  -u "operator:NEW_PASSWORD" \
  -o angevoice-diagnostics.zip

诊断 ZIP 不包含明文 API Key 或管理员密码。模型资产修复可能重新下载文件，运行中的模型默认不会被强制中断。.pt 音色上传仍只允许可信来源，且公网场景不建议开放。

输出格式

启用方式：管理后台打开“启用 FFmpeg 转码”，或设置 ANGEVOICE_FFMPEG_ENABLED=true。旧 KOKORO_MP3_ENABLED=true 仍兼容视为启用转码。常用环境变量：

可通过 GET /v1/audio/formats 查询当前可用格式、FFmpeg 是否启用以及容器中是否安装了 ffmpeg。WebSocket 流式暂不输出 OGG/MP3/M4A，仍使用 pcm_s16le 或 wav 分包。

转码相关结构化错误码：

流式解码参数配置

以下环境变量控制 WebSocket 流式合成中的分段解码策略，适用于需要精细调节合成延迟和内存占用的场景。

这三个阈值（LOW < MID < HIGH）不是显存占用比例，而是“已生成音频领先实时播放的秒数”。余量越少，解码越小块，优先降低首包延迟；余量越充足，解码块越大，减少块间抖动。

空闲超时自动释放显存

在 GPU 部署场景中，多模型共存会占用大量显存。启用空闲超时后，所有已加载模型（包括当前选中的模型）在空闲一段时间后会被自动卸载以释放显存/内存，下次请求时再自动重新加载，对调用方完全透明。

工作原理：

1. 系统每隔 ANGEVOICE_IDLE_CHECK_INTERVAL 秒检查一次各模型的最后请求时间
2. 如果某个已加载模型已空闲超过 ANGEVOICE_IDLE_TIMEOUT_SECONDS 秒，自动调用卸载
3. 下一次对该模型发起的 API 请求会先触发重新加载，加载完成后正常返回合成结果
4. 默认也会释放当前活跃模型；如需保持当前模型常驻，可设置 ANGEVOICE_IDLE_UNLOAD_CURRENT=false
5. 如启用 ANGEVOICE_RESTART_AFTER_IDLE_UNLOAD=true，系统只会在这次空闲卸载成功后、且无活跃请求和 WebSocket 连接时安排一次进程退出；退出由 Docker/服务管理器自动拉起，不会在单纯空闲但没有发生卸载时循环重启

推荐配置：

# 30 分钟无请求自动释放显存，每 30 秒检查一次
ANGEVOICE_IDLE_TIMEOUT_SECONDS=1800
ANGEVOICE_IDLE_CHECK_INTERVAL=30

注意：重新加载模型需要一定时间（通常几秒到十几秒），首次请求的延迟会略高。如果显存/内存充裕，可以设置 ANGEVOICE_IDLE_TIMEOUT_SECONDS=0 禁用空闲卸载。彻底清理功能默认关闭，只有在需要清理 CUDA/ONNX Runtime 底层残留且容器具备自动重启策略时才建议开启。

统一请求契约与动态参数

HTTP 与 WebSocket 使用一致的合成参数与参考音频语义。当选择已保存的 Voice Profile 时，服务端只采用该 Profile 中保存的参考音频和参考文本，不使用页面中残留的临时参考条件。Studio 的网页录音、上传、试听、改名和删除均使用统一的 Profile 与参考音频接口；旧 ZipVoice 路由仅保留用于兼容已有客户端。对于 ZipVoice，参考录音界面会提示官方建议少于 3 秒；服务端允许最长 15 秒且不自动截取，超过建议长度会返回提示信息，超过上限才拒绝。浏览器录音要求 HTTPS 或 localhost 安全来源。

动态引擎参数可通过模型能力信息或下列接口发现：

GET /v1/engines/parameter-schema

ZipVoice 当前提供的兼容参数如下：

HTTP multipart 仍可直接提交以上旧字段；OpenAI 风格 JSON 还可在 engine_params 对象中发送参数：

{
  "model": "zipvoice",
  "text": "正文内容",
  "voice": "saved_voice_id",
  "engine_params": {
    "zipvoice_num_steps": 8,
    "zipvoice_remove_long_sil": false
  }
}

WebSocket 首包同样接受 engine_params。ZipVoice 当前实现为分句流式，而非字级或 token 级实时输出；早期 CPU NAS 首段实测延迟约 19.38 秒，因此实时定位只能由最终 CPU/GPU 实测门槛决定。标准 GPU 支持 CUDA 路线，并保留 CPU 自动回退；实际性能请以目标主机诊断数据为准。

常见错误

| KOKORO_PROCESS_ISOLATION_ENABLED | 程序默认 false；正式模板 true | 是否将 Kokoro 运行于可销毁 Worker；释放后用于回收主机内存与显存 | | MOSS_PROCESS_ISOLATION_ENABLED | 程序默认 false；正式模板 true | 是否启用 MOSS 进程级隔离；Docker/fnOS 正式模板默认开启，超时或底层卡死时可终止 worker 并恢复 | | MOSS_PROCESS_ISOLATION_PROVIDERS | 程序默认 cuda；正式模板 cpu,cuda | 哪些 provider 使用隔离子进程 | | MOSS_PROCESS_KILL_GRACE_SECONDS | 2 | worker 超时后终止/强杀的宽限秒数 | | ANGEVOICE_WEBSOCKET_STREAM_IDLE_TIMEOUT_SECONDS | 120 | WebSocket 长文本流式空闲等待窗口 | | ANGEVOICE_ENGINE_PROCESS_STREAM_DRAIN_SECONDS | 30 | 隔离 Worker 取消后的排空等待窗口 | | ANGEVOICE_ENGINE_PROCESS_STREAM_IDLE_TIMEOUT_SECONDS | 120 | 隔离 Worker 流式空闲等待窗口 | | ZIPVOICE_PROCESS_ISOLATION_ENABLED | 程序默认 false；正式模板 true | 是否将 ZipVoice 运行于可销毁 Worker；NAS/GPU 长驻部署建议开启 | | ANGEVOICE_ENGINE_PROCESS_KILL_GRACE_SECONDS | 2 | Kokoro/ZipVoice Worker 释放时的优雅退出宽限秒数 | | ANGEVOICE_STARTUP_PRELOAD_ENABLED | false | 是否启动时通过 Worker 预载模型；默认关闭以保持空闲低占用 | | ANGEVOICE_STARTUP_PRELOAD_MODEL | kokoro | 启动预载目标模型 |

管理后台页面

浏览器访问：

GET /admin

开启方式：

KOKORO_ADMIN_ENABLED=true
ANGEVOICE_ADMIN_USERNAME=admin
ANGEVOICE_ADMIN_PASSWORD='admin123'  # 首次进入默认值，登录后立即改密

/admin 使用 HTTP Basic 登录。Docker 部署支持中文管理员用户名以及字母、数字和 _ . @ -；首次以默认凭据登录后，应立即在管理页保存新的哈希化凭据。

管理页面提供五个区块：

• Dashboard：当前模型、缓存、请求、音频质量概览。
• Models：加载、切换、释放、强制释放模型，并校验/修复模型资产。
• Tuning：MOSS 长文本、流式、静音压缩、crossfade、峰值保护、空闲卸载和“空闲后彻底清理”等参数；内置 NAS 稳定、长文本旁白、低延迟流式、克隆质量优先四个预设。
• Security：默认凭据风险提示、API Key 状态/查看/轮换，以及支持中文用户名的持久化改密。
• Diagnostics：最近请求、last_output_quality、ENV patch、脱敏诊断 ZIP、版本更新提示和折叠的原始 JSON。

后台保存配置会写入 ANGEVOICE_RUNTIME_CONFIG_FILE，Docker 默认 /app/config/runtime-config.json。启动加载顺序是代码默认值、环境变量、runtime-config，所以上次在后台保存的值会在重启后继续生效。页面也可以导出 ENV patch，方便把最终参数固化到 .env。

常用 Admin API：

在 GitHub 查看原始文档 ↗