ANGEHUB.COM
EN
Docs/AngeVoice

AngeVoice API 参考

先使用 OpenAI 风格的语音接口。只有需要上传参考音频或兼容旧客户端时，才使用 /api/tts。

RESTWebSocketBearer Token

地址和认证

部署方式HTTPWebSocket
CPUhttp://host:8100ws://host:8100/ws/v1/tts
标准 GPUhttp://host:8101ws://host:8101/ws/v1/tts
Legacy GPUhttp://host:8102ws://host:8102/ws/v1/tts

受保护接口使用：

Authorization: Bearer YOUR_TOKEN

状态和能力发现

方法路径用途
GET/health服务、模型和运行时状态
GET/v1/models可用模型与 Provider
GET/v1/models/current当前模型和回退状态
GET/v1/tts/capabilities格式、编码和音色能力
GET/v1/audio/voices音色列表
GET/v1/audio/formats输出格式和 FFmpeg 状态
GET/v1/engines/parameter-schema模型专属参数 Schema

模型加载和切换

方法路径用途
POST/v1/models/{model}/load预先加载指定模型
POST/v1/models/switch切换模型，并可释放旧模型
POST/v1/models/{model}/unload释放指定模型
curl -X POST "$BASE_URL/v1/models/switch" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"model":"moss","unload_previous":true}'

OpenAI 风格语音合成

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 speech.wav

输出格式和编码

以 /v1/audio/formats 返回值为准。WAV 和 PCM 是基础路径；MP3、OGG、M4A 和 telegram_voice 需要对应转码能力。需要 JSON 响应时使用 response_encoding=base64。

成功响应会携带请求 ID；排障时优先记录请求 ID，不要记录完整 Token。

参考音频克隆

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

ZipVoice 请求还应提供 prompt_text。服务端默认参考音频可通过 MOSS_PROMPT_AUDIO_PATH 配置。

WebSocket 流式合成

{
  "model": "kokoro",
  "text": "你好世界，这是一段流式测试。",
  "voice": "zm_010",
  "format": "pcm_s16le",
  "binary": false,
  "token": "YOUR_TOKEN"
}

发送 {"type":"cancel"} 可取消后续分段。已进入同步推理的当前分段可能会先完成。

批量和取消

方法路径说明
POST/v1/audio/batch多段文本打包为 ZIP
POST/v1/audio/requests/{request_id}/cancel取消 HTTP 或批量请求
GET/requests查看最近请求状态
curl -X POST "$BASE_URL/v1/audio/batch" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "model":"kokoro",
    "voice":"zm_010",
    "response_format":"wav",
    "items":[
      {"text":"第一段","filename":"001"},
      {"text":"第二段","filename":"002"}
    ]
  }' \
  --output speech-batch.zip

Voice Profile

在 Studio 中保存的 Voice Profile 会出现在音色列表中，并可作为 voice 使用。调用前可通过 /v1/audio/voices?detail=true 查询可用 Profile、模型归属和音色详情。

交互式文档