微软文本转语音 API 文档

基于微软 Azure Speech Service 的文字转语音接口。支持两种调用模式：通用模式（参数构建 SSML）与 SSML 模式（直接传入完整 SSML）；并支持流式 / 关闭流式 / 异步（长文本批量） 三种交付方式。

接口信息

项目	值
合成接口	`POST /api/v1/microsoft-tts`
异步状态查询	`POST /api/v1/microsoft-tts-status`
请求格式	`application/json`（也兼容 `application/x-www-form-urlencoded`）
认证方式	`Authorization: Bearer <API_KEY>`

请求参数

两种模式二选一（同时传 text 与 ssml 时以 ssml 为准）：

模式一：通用模式（参数构建 SSML）

仅 text 必填，其余可选。

参数	类型	必填	默认值	说明
`text`	string	✅	-	要合成的文本内容（服务端未强制长度；同步建议 ≤ 5000，异步建议 ≤ 100000）
`voice`	string	❌	`zh-CN-XiaoxiaoNeural`	音色名称
`language`	string	❌	`zh-CN`	语言代码，写入 SSML 的 `xml:lang`
`rate`	string	❌	`0`	语速（相对百分比，`10` = +10%，`-10` = -10%；`0` 不写入）
`volume`	string	❌	`100`	音量（绝对 0-100，`0` 为静音；非空即写入）
`pitch`	string	❌	`0`	音调（相对百分比，`2` = +2%；`0` 不写入）
`style`	string	❌	`general`	说话风格；空或 `general` = 不指定
`role`	string	❌	`general`	角色风格；仅 `style` 生效时才写入
`styledegree`	string	❌	`1`	风格强度 0.01-2.0；`1` 不写入
`kbitrate`	string	❌	`audio-48khz-96kbitrate-mono-mp3`	音频编码与质量
`backgroundaudio`	string	❌	-	背景音直链（http/https）
`backgroundvolume`	string	❌	-	背景音音量 0-100
`stream`	boolean	❌	`true`	`true`=流式返回音频二进制；`false`=保存音频并返回 `audio_url`
`async`	boolean	❌	`false`	`true`=提交长文本批量任务并返回 `task_id`

请求示例：

{
    "text": "您好，这是一个 Microsoft TTS 语音合成示例。",
    "voice": "zh-CN-XiaoxiaoNeural",
    "style": "friendly",
    "rate": "10",
    "stream": true
}

模式二：SSML 模式

仅 ssml 必填。

参数	类型	必填	默认值	说明
`ssml`	string	✅	-	完整 SSML 文档：必须含 `<speak>`、至少一个 `<voice>`，且含命名空间 `xmlns="http://www.w3.org/2001/10/synthesis"`；必须是良构 XML
`kbitrate`	string	❌	`audio-48khz-96kbitrate-mono-mp3`	音频编码与质量
`stream`	boolean	❌	`true`	同模式一
`async`	boolean	❌	`false`	同模式一

请求示例：

{
    "ssml": "<speak version=\"1.0\" xmlns=\"http://www.w3.org/2001/10/synthesis\" xmlns:mstts=\"http://www.w3.org/2001/mstts\" xml:lang=\"zh-CN\"><voice name=\"zh-CN-XiaoxiaoNeural\"><mstts:express-as style=\"friendly\">您好，这是 SSML 示例。</mstts:express-as></voice></speak>"
}

三种交付方式

方式	参数	成功响应	计费时机
流式	`async=false, stream=true`（默认）	`audio/mpeg` 二进制（chunked + `X-Characters`/`X-Cost`）	收到首个音频字节时扣费
关闭流式	`async=false, stream=false`	JSON，音频地址在 `data.audio_url`	音频落盘后扣费
异步（长文本）	`async=true`	JSON，返回 `task_id`，再用 `-status` 轮询	提交时扣费，失败自动退款

响应格式

一、流式（`stream=true`）

成功：HTTP 200，响应体是 audio/mpeg 二进制（不是 JSON）

Content-Type: audio/mpeg
Transfer-Encoding: chunked
X-Accel-Buffering: no
X-Characters: 42
X-Cost: 0.01
Access-Control-Expose-Headers: X-Characters, X-Cost

二、关闭流式（`stream=false`）

成功：HTTP 200，JSON

{
    "code": 200,
    "message": "合成成功",
    "data": {
        "audio_url": "http://your-site/wp-content/uploads/my-document/audio/processed/1791448781_21220898.mp3",
        "format": "mp3",
        "char_count": 17,
        "cost": 0.001,
        "balance": 2.265
    }
}

三、异步（`async=true`）

提交成功：HTTP 200

{
    "code": 200,
    "message": "任务已提交，正在处理中",
    "data": { "task_id": "808_1852492485_1791445288", "char_count": 21, "cost": 0.001, "balance": 2.266 }
}

轮询：POST /api/v1/microsoft-tts-status，body { "task_id": "..." }；三种状态都是 HTTP 200，靠 data.status 区分：

{ "code": 200, "message": "ok", "data": { "task_id": "808_…", "status": "processing", "progress": 50 } }

{ "code": 200, "message": "ok", "data": { "task_id": "808_…", "status": "completed", "progress": 100, "zip_url": "http://your-site/wp-content/uploads/…/tts_808_….zip" } }

{ "code": 200, "message": "ok", "data": { "task_id": "808_…", "status": "failed", "progress": 0, "msg": "合成失败，费用已退回" } }

completed 的 zip_url 是已转存到本站的压缩包（内含 0001.mp3），不会给几天后就失效的临时链接。

错误响应

统一信封：{ "code": <HTTP 状态码>, "error": "<错误码>", "message": "<描述>" }

{ "code": 400, "error": "invalid_ssml", "message": "SSML格式不正确，必须包含<voice>标签" }

鉴权失败由 WP REST 中间件直接返回，形态不同：

{ "code": "rest_invalid_api_key", "message": "API密钥无效", "data": { "status": 401 } }

错误码

错误码	HTTP	说明
`method_not_allowed`	405	非 POST 请求
`rest_forbidden` / `rest_invalid_auth` / `rest_missing_api_key` / `rest_invalid_api_key`	401	鉴权失败（WP REST 形态）
`empty_text`	400	`text` 与 `ssml` 均为空
`invalid_ssml`	400	SSML 校验失败（缺 `<speak>` / `<voice>` / 命名空间，或非良构 XML）
`missing_task_id`	400	状态查询未传 `task_id`
`insufficient_balance`	403	余额不足
`task_not_found`	404	状态查询：任务不存在或非本人
`missing_config`	500	语音合成账户未配置
`save_failed`	500	关闭流式时音频保存失败（此时不会扣费）
`task_create_failed`	500	异步建任务落库失败（已自动退款）
`api_error`	服务端状态码 / 500 / 502	合成请求失败或业务错误
`parse_error`	500	响应无法解析

计费说明

字符数计算规则

中文字符（Unicode Script=Han）：计 2 个字符

其他字符（字母、数字、标点、空格、日文假名、韩文等）：计 1 个字符

SSML：剥离全部标签并还原实体后再统计（标签不计费），与模式无关

计费公式

扣费点数 = 超出免费额度的字符数 × 单价 × 折扣

单价与折扣由系统配置决定；有免费额度时优先消耗额度（VIP 走 api_free、永久会员走 perm_free）。

计费时机

方式	时机
流式（`stream=true`）	首个音频字节到达时扣费；中途 curl 中断自动退款
关闭流式（`stream=false`）	先落盘再扣费：落盘失败就一分钱不扣
异步（`async=true`）	提交时即扣费并建订单；任务失败按提交时的额度分解精确回滚 + 原路退款

扣费成功后创建订单记录（记录字符数、扣费点数）。

SSML 构建规则

通用模式下服务端自动构建 SSML。总原则：空即不传（空值一律不输出该属性/元素）。

命名空间

<speak version="1.0"
       xmlns="http://www.w3.org/2001/10/synthesis"
       xmlns:mstts="http://www.w3.org/2001/mstts"
       xml:lang="{language}">

参数转换规则

参数	规则
`rate`	纯数字自动补 `%`（`10` → `rate="10%"`）；`0` / `0%` / 空 → 不输出
`pitch`	同 `rate`
`volume`	空 → 不输出；其他值原样输出（`100` 也会写入，等价默认音量）
`style`	空或 `general` → 整个 `<mstts:express-as>` 不输出（`role`、`styledegree` 随之失效）
`role`	空 / `general` / `null` → 不输出；仅当 `style` 生效时才会写入
`styledegree`	空或 `1` → 不输出；服务端不钳制范围
`backgroundaudio`	非空 → 输出 `<mstts:backgroundaudio src="…" [volume="…"] fadein="3000" fadeout="4000"/>`，且必须是 `<speak>` 的第一个子元素

属性顺序：<mstts:express-as> 内为 role → style → styledegree；<prosody> 内为 volume → rate → pitch。
多语言音色 zh-CN-XiaoxiaoDialectsNeural 会自动用 <lang xml:lang="…"> 包裹文本。

文本转义

正文不自动转义，行内标签（如 <break time="0.5s"/>、<phoneme>、<say-as>）会被原样保留并生效。
但裸 & 与 < 会让 SSML 非良构而被拒绝（400 invalid_ssml），需要写成 & 与 <。

SSML 结构示例（服务端实际输出样式）

<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis" xmlns:mstts="http://www.w3.org/2001/mstts" xml:lang="zh-CN">
        <mstts:backgroundaudio src="https://example.com/bgm.mp3" volume="50" fadein="3000" fadeout="4000"/>
        <voice name="zh-CN-XiaoxiaoNeural">
            <mstts:express-as role="YoungAdultFemale" style="friendly" styledegree="1.5">
                <prosody volume="90" rate="10%" pitch="2%">
                    您好，这是一个示例。
                </prosody>
            </mstts:express-as>
        </voice>
    </speak>

SSML 模式下服务端只读校验、不改写：整份文档原样透传。

参考数据

常用音色

音色名称	语言	性别
`zh-CN-XiaoxiaoNeural`	中文（简体）	女
`zh-CN-YunxiNeural`	中文（简体）	男
`zh-CN-XiaoyiNeural`	中文（简体）	女
`zh-CN-YunyangNeural`	中文（简体）	男
`en-US-JennyNeural`	英语（美国）	女
`en-US-GuyNeural`	英语（美国）	男
`ja-JP-NanamiNeural`	日语	女

完整列表见微软官方语言支持：语音、区域设置、语言

常用风格（style）

friendly、excited、sad、angry、calm、cheerful、fearful、whispering、newscast、customerservice、assistant 等（general 为「不指定」，不是有效风格值）。

角色（role）

Girl、Boy、YoungAdultFemale、YoungAdultMale、OlderAdultFemale、OlderAdultMale、SeniorFemale、SeniorMale

音频质量（kbitrate）

值	说明
`audio-48khz-96kbitrate-mono-mp3`	48kHz 96kbps 单声道 MP3（默认）
`audio-24khz-48kbitrate-mono-mp3`	24kHz 48kbps 单声道 MP3
`audio-16khz-32kbitrate-mono-mp3`	16kHz 32kbps 单声道 MP3

调用示例

cURL：流式（直接落地为 mp3）

cURL：关闭流式（拿 audio_url）

cURL：异步长文本（提交 + 轮询）

PHP：关闭流式

参考文档

application/json

Bodyapplication/json

示例

同步开启流式同步关闭流式异步响应

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization, X-Requested-With
Access-Control-Expose-Headers: X-Characters, X-Cost
Content-Type: audio/mpeg
Transfer-Encoding: chunked
X-Accel-Buffering: no
X-Characters: 42
X-Cost: 0.01

<MP3 二进制字节流…>

接口信息

请求参数

模式一：通用模式（参数构建 SSML）

模式二：SSML 模式

三种交付方式

响应格式

一、流式（`stream=true`）

二、关闭流式（`stream=false`）

三、异步（`async=true`）

错误响应

错误码

计费说明

字符数计算规则

计费公式

计费时机

SSML 构建规则

命名空间

参数转换规则

文本转义

SSML 结构示例（服务端实际输出样式）

参考数据

常用音色

常用风格（style）

角色（role）

音频质量（kbitrate）

调用示例

cURL：流式（直接落地为 mp3）

cURL：关闭流式（拿 audio_url）

cURL：异步长文本（提交 + 轮询）

PHP：关闭流式

参考文档

请求参数

请求示例代码

返回响应

微软文本转语音 API 文档

接口信息#

请求参数#

模式一：通用模式（参数构建 SSML）#

模式二：SSML 模式#

三种交付方式#

响应格式#

一、流式（stream=true）#

二、关闭流式（stream=false）#

三、异步（async=true）#

错误响应#

错误码#

计费说明#

字符数计算规则#

计费公式#

计费时机#

SSML 构建规则#

命名空间#

参数转换规则#

文本转义#

SSML 结构示例（服务端实际输出样式）#

参考数据#

常用音色#

常用风格（style）#

角色（role）#

音频质量（kbitrate）#

调用示例#

cURL：流式（直接落地为 mp3）#

cURL：关闭流式（拿 audio_url）#

cURL：异步长文本（提交 + 轮询）#

PHP：关闭流式#

参考文档#

请求参数

请求示例代码

返回响应

接口信息

请求参数

模式一：通用模式（参数构建 SSML）

模式二：SSML 模式

三种交付方式

响应格式

一、流式（`stream=true`）

二、关闭流式（`stream=false`）

三、异步（`async=true`）

错误响应

错误码

计费说明

字符数计算规则

计费公式

计费时机

SSML 构建规则

命名空间

参数转换规则

文本转义

SSML 结构示例（服务端实际输出样式）

参考数据

常用音色

常用风格（style）

角色（role）

音频质量（kbitrate）

调用示例

cURL：流式（直接落地为 mp3）

cURL：关闭流式（拿 audio_url）

cURL：异步长文本（提交 + 轮询）

PHP：关闭流式

参考文档