MSTTS 语音服务

快速开始

根据使用场景选择入口。只想给阅读类软件添加语音时，不需要手写接口参数。

1. 打开 /reader。
2. 选择目标软件：阅读或爱阅记。
3. 选择生成模式：固定链接或自定义语音列表。
4. 选择一个或多个语言、音色、输出格式，生成配置。
5. 复制导入链接或 JSON，到对应软件里导入。

阅读配置生成器

/reader 是给最终用户准备的图形页面，用来生成阅读和爱阅记可以使用的 TTS 配置。

两种生成模式

常用选项

文本转语音 API

/mstts 用于把文本或 SSML 合成为音频。服务会自动获取并缓存微软 token，token 失效时会自动刷新。

最小 JSON 示例

{
  "text": "你好，欢迎使用微软语音服务。",
  "voice": "zh-CN-XiaoxiaoNeural",
  "format": "audio-24khz-48kbitrate-mono-mp3"
}

GET 示例

/mstts?text=你好&voice=zh-CN-XiaoxiaoNeural&format=audio-24khz-48kbitrate-mono-mp3

直接传 SSML

传入 ssml 后，服务会直接把这段 SSML 发给微软，不再自动拼接 voice、style、rate 等参数。

{
  "ssml": "<speak version=\"1.0\" xml:lang=\"zh-CN\" xmlns=\"http://www.w3.org/2001/10/synthesis\"><voice name=\"zh-CN-XiaoxiaoNeural\">你好</voice></speak>",
  "format": "audio-24khz-48kbitrate-mono-mp3"
}

常用参数

不传 ssml 时，服务会按这些字段自动拼接 SSML；传入 ssml 后只保留 format 作为输出格式。

HD 音色参数

HD 参数只会在 HD 音色上写入到 <voice parameters>。普通音色不会带入这些字段；微软官方说明中 HD 音色的 SSML 元素支持比普通音色少，prosody 类参数可能被微软忽略。

{
  "text": "Hello, this is an HD voice.",
  "voice": "en-US-Ava:DragonHDOmniLatestNeural",
  "temperature": 0.7,
  "top_p": 0.7,
  "top_k": 22,
  "cfg_scale": 1.4,
  "format": "audio-48khz-192kbitrate-mono-mp3"
}

音色与格式查询

[
  {
    "id": 23,
    "value": "audio-48khz-192kbitrate-mono-mp3"
  }
]

Region 与 Token

服务会自动从微软接口获取 token 和 region。通常不需要手动调用 /mstts/gettoken，只有排查 region 或单独接入时才需要。

GET /mstts/gettoken
GET /mstts/gettoken?regions=southeastasia
GET /mstts/gettoken?regions=southeastasia&regions=eastus&regions=westeurope
GET /mstts/gettoken?anyRegion=true

默认 Region 与差异

默认首选 southeastasia、eastus、westeurope。这三个 region 是当前公共预览语音测试中覆盖最完整的返回区域，优先用于减少 HD、Preview 和 multi-talker 音色缺失。

同一个接口还能拿到 eastasia、northeurope、westus 等 region；这些区域可以用于常规音色，但公共预览、HD、multi-talker 或新增音色的覆盖可能少于默认三项。具体音色不要写死，建议用 /mstts/getvoice 或管理后台的“获取可用 Region”按当前返回确认。

管理后台

/admin 用账号密码登录，不使用 ApiAuth.Token。后台可以修改配置、刷新微软 token、查看 data 目录状态、统计和清理自定义配置快照。

配置页默认用有序列表管理 Region 优先级。点击“获取可用 Region”后，勾选会追加到列表末尾，取消勾选会从列表移除；点击已选 Region 可以展开上移、下移和移除操作。手动文本编辑保留在“自定义编辑”折叠项里。

首次登录

1. 启动服务后打开 /admin。
2. 使用 /app/data/admin-initial-password.txt 里的临时密码登录。
3. 首次登录后修改密码。

部署与鉴权

配置文件位置

Docker 部署推荐挂载整个 /app/data 目录。首次启动时，如果 /app/data/appsettings.json 不存在，服务会自动创建一份默认配置。

docker run -d \
  --name mstts \
  -p 8080:8080 \
  -v /data/mstts:/app/data \
  hejd/mstts:latest

Docker Compose 示例：

services:
  mstts:
    image: hejd/mstts:latest
    container_name: mstts
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - "/data/mstts:/app/data"

常用配置

{
  "ApiAuth": {
    "Token": ""
  },
  "MicrosoftTranslatorToken": {
    "PreferredRegions": [
      "southeastasia",
      "eastus",
      "westeurope"
    ],
    "RegionSelectionMode": "Priority",
    "RegionMatchMaxAttempts": 30
  },
  "ReaderConfig": {
    "PublicBaseUrl": "",
    "SnapshotRetentionDays": 0,
    "ShareTokenSecret": ""
  },
  "Admin": {
    "Enabled": true,
    "Username": "admin",
    "PasswordHash": "",
    "ForcePasswordChange": true,
    "SessionDays": 7
  }
}

启用鉴权后的调用方式

curl -H "X-Api-Token: your-token" \
  "http://localhost:8080/mstts/getvoice"

http://localhost:8080/mstts?text=测试&voice=zh-CN-XiaoxiaoNeural&apiToken=your-token