微软语音合成Microsoft-TTS-API文档

前言说明

微软 TTS 作为企业级 AI 语音服务，以高拟真、强稳定、全球化的特性广泛应用于各行业。我们深度整合微软 TTS 技术能力，面向企业与开发者提供标准化 API 接口，覆盖多音色、多语言、自定义发音与音频格式等需求，提供稳定可靠的服务支撑与技术保障，助力业务快速落地语音合成场景，提升产品体验与服务效率。

相较于微软官方 Azure 语音合成，接口使用体验全面优化，仅需 10 元即可生成 50 万字符，低成本高效能。

接口概述

Microsoft TTS API 提供专业的语音合成服务，支持丰富音色选择，可灵活调节语速、音量、音调等核心参数。推荐在调用时传入 SSML 格式文本，能进一步自定义停顿、语气、发音结构等细节，实现更精细、更自然的语音效果。

主要特性

支持普通文本和 SSML 两种输入方式
丰富的音色库（多语言多角色）
可调节语速、音量、音调、说话风格等
计费精确到字符级别（中文字符计2，其他计1）
支持会员免费额度和折扣
直接返回音频二进制数据

请求方式

接口地址

请求方法	地址
POST	https://www.yuntts.com/api/v1/microsoft-tts

API Key 认证

所有请求需要在请求头中携带 Bearer Token 进行认证。

请求头格式：

http 复制代码

Authorization: Bearer {your_api_key}
Content-Type: application/json

请求参数

基础参数

参数名	类型	必填	默认值	说明
text	string	否*	-	普通文本内容，text和ssml二选一
ssml	string	否*	-	SSML内容，text和ssml二选一

语音参数

参数名	类型	必填	默认值	说明
voice	string	否	`zh-CN-XiaoxiaoNeural`	音色标识，见下方音色列表
language	string	否	`zh-CN`	语言代码
rate	string/int	否	`0`	语速，范围-100到200，或百分比格式如`+10%`
volume	string/int	否	`0`	音量，范围0到100
pitch	string/int	否	`0`	音调，范围-100到100，或百分比格式如`+5%`
style	string	否	`general`	说话风格，见下方风格列表
role	string	否	`general`	角色风格，见下方角色列表
styledegree	string/int	否	1	感情强度，范围0.1到2
kbitrate	string	否	audio-48khz-96kbitrate-mono-mp3	音频码率，见下方码率列表

音色列表

中文（zh-CN）

音色标识	说明
zh-CN-XiaoxiaoNeural	晓晓（女声）
zh-CN-YunxiNeural	云希（男声）
zh-CN-YunyangNeural	云扬（男声）
zh-CN-XiaohanNeural	晓涵（女声）
zh-CN-XiaomengNeural	晓梦（女声）
zh-CN-XiaoxuanNeural	晓萱（女声）
zh-CN-YunhaoNeural	云皓（男声）
zh-CN-YunyeNeural	云野（男声）

更多音色请参考 Microsoft 音色官方文档。

音色感情风格

说话风格列表、角色风格列表，请参考 Microsoft音色感情风格官方文档。

音频码率列表

码率值	说明
audio-16khz-32kbitrate-mono-mp3	16kHz 32kbps MP3（默认）
audio-16khz-64kbitrate-mono-mp3	16kHz 64kbps MP3
audio-16khz-128kbitrate-mono-mp3	16kHz 128kbps MP3
audio-24khz-48kbitrate-mono-mp3	24kHz 48kbps MP3
audio-24khz-96kbitrate-mono-mp3	24kHz 96kbps MP3
audio-24khz-160kbitrate-mono-mp3	24kHz 160kbps MP3

更多音色请参考 Microsoft 官方文档或参考《音频格式全解析：编码、采样率与封装格式的深度剖析》。

响应说明

成功响应（音频）

当合成成功时，接口直接返回音频二进制数据。

响应头：

http 复制代码

Content-Type: audio/mpeg
Content-Length: {audio_size}
X-Characters: {char_count}
X-Cost: {cost_amount}
Access-Control-Allow-Origin: *

响应头	说明
X-Characters	本次合成的字符数
X-Cost	本次合成的费用

响应体： 音频二进制数据（MP3/WAV格式）

成功响应（JSON）

某些情况下（如批量任务）可能返回 JSON 格式。

json 复制代码

{
  "code": 200,
  "message": "成功",
  "data": {
    // 接口返回的数据
  }
}

错误响应

json 复制代码

{
  "code": 400,
  "error": "error_code",
  "message": "错误描述信息"
}

代码示例

PHP (cURL) - 文本模式

php 复制代码

<?php

function synthesizeText($text, $apiKey, $outputPath) {
    $apiUrl = 'https://www.yuntts.com/api/v1/microsoft-tts';

    $params = [
        'text' => $text,
        'voice' => 'zh-CN-XiaoxiaoNeural',
        'language' => 'zh-CN',
        'rate' => 0,
        'volume' => 0,
        'pitch' => 0,
        'style' => 'general',
        'kbitrate' => 'audio-16khz-32kbitrate-mono-mp3'
    ];

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $apiUrl);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HEADER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'Authorization: Bearer ' . $apiKey
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    $headerSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
    curl_close($ch);

    // 分离响应头和响应体
    $headers = substr($response, 0, $headerSize);
    $body = substr($response, $headerSize);

    // 解析响应头获取字符数和费用
    $charCount = '';
    $cost = '';
    foreach (explode("\r\n", $headers) as $line) {
        if (strpos($line, 'X-Characters:') === 0) {
            $charCount = trim(substr($line, 13));
        }
        if (strpos($line, 'X-Cost:') === 0) {
            $cost = trim(substr($line, 7));
        }
    }

    if ($httpCode !== 200) {
        $error = json_decode($body, true);
        throw new Exception($error['message'] ?? '请求失败');
    }

    echo "字符数: $charCount, 费用: $cost\n";

    // 保存音频文件
    file_put_contents($outputPath, $body);
    echo "音频已保存到: $outputPath\n";

    return $outputPath;
}

// 使用示例
try {
    synthesizeText('欢迎使用 Microsoft 语音合成服务！', 'your_api_key', 'output.mp3');
} catch (Exception $e) {
    echo '错误: ' . $e->getMessage() . "\n";
}

PHP (cURL) - SSML 模式

php 复制代码

<?php

function synthesizeSSML($apiKey, $outputPath) {
    $apiUrl = 'https://www.yuntts.com/api/v1/microsoft-tts';

    // 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">
  <voice name="zh-CN-XiaoxiaoNeural">
    <prosody rate="+10%" pitch="+5%">
      欢迎使用 Microsoft SSML 语音合成！
    </prosody>
  </voice>
</speak>';

    $params = [
        'ssml' => $ssml,
        'kbitrate' => 'audio-16khz-32kbitrate-mono-mp3'
    ];

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $apiUrl);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HEADER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'Authorization: Bearer ' . $apiKey
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    $headerSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
    curl_close($ch);

    // 分离响应头和响应体
    $headers = substr($response, 0, $headerSize);
    $body = substr($response, $headerSize);

    // 解析响应头获取字符数和费用
    $charCount = '';
    $cost = '';
    foreach (explode("\r\n", $headers) as $line) {
        if (strpos($line, 'X-Characters:') === 0) {
            $charCount = trim(substr($line, 13));
        }
        if (strpos($line, 'X-Cost:') === 0) {
            $cost = trim(substr($line, 7));
        }
    }

    if ($httpCode !== 200) {        $error = json_decode($body, true);
        throw new Exception($error['message'] ?? '请求失败');
    }

    echo "字符数: $charCount, 费用: $cost\n";

    // 保存音频文件
    file_put_contents($outputPath, $body);
    echo "音频已保存到: $outputPath\n";

    return $outputPath;
}

// 使用示例
try {
    synthesizeSSML('your_api_key', 'output.mp3');
} catch (Exception $e) {
    echo '错误: ' . $e->getMessage() . "\n";
}

错误码说明

HTTP 状态码	错误码	说明
400	`method_not_allowed`	请求方法不允许，请使用 POST
400	`empty_text`	文本或SSML内容不能为空
400	`invalid_ssml`	SSML格式不正确
400	`missing_prompt_audio`	缺少提示音频（其他接口可能用到）
401	`empty_key`	Authorization头为空
401	`invalid_key`	API密钥无效
403	`insufficient_balance`	余额不足
500	`api_error`	API请求失败
500	`parse_error`	响应解析失败
500	`save_failed`	音频保存失败

常见问题

Q1: 如何获取 API Key？

A: 登录会员中心，进入「API密钥」，在那里可以创建和管理您的 API Key。

Q2: 中文字符和英文字符计费有什么区别？

A: 中文字符按2个字符计费，英文字符及其他字符按1个字符计费。

Q3: 会员有什么优惠？

A: VIP 和 SVIP 会员享受每月免费字符额度，超出部分享受折扣优惠。具体比例请在后台设置中查看。

Q4: 支持哪些音频格式？

A: 主要支持 MP3 格式，可选多种码率。也支持 WAV、OGG 等格式（通过 kbitrate 参数选择）。

Q5: 如何使用 SSML 格式？

A: 将 textType 设置为 ssml，并在 ssml 参数中传入完整的 SSML 内容。SSML 需要包含标准的命名空间声明。

SSML 示例：

xml 复制代码

<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">
    <prosody rate="+10%" pitch="+5%">
      欢迎使用 Microsoft 语音合成服务！
    </prosody>
  </voice>
</speak>

Q6: 接口超时时间是多少？

A: 接口超时时间为 60 秒，请确保您的请求在这个时间内完成。

Q7: 如何测试接口？

A: 我们提供了测试页面，您可以在浏览器中打开它，输入您的 API Key 进行测试。

Q8: 接口返回的音频可以直接播放吗？

A: 可以，接口返回的是标准的音频二进制数据，可以直接在浏览器中播放或保存为文件。