文本转语音 REST API

项目
07/19/2024

利用语音服务，可以通过使用 REST API 针对某个区域将文本转换为合成语音并获取受支持声音的列表。本文介绍授权选项、查询选项、如何构建请求以及如何解释响应。

提示

文本转语音 REST API 的用例受到限制。仅在无法使用语音 SDK 的情况下使用它。例如，使用语音 SDK 可以订阅事件以详细了解有关文本转语音的处理和结果信息。

文本转语音 REST API 支持许多区域设置中的神经文本转语音语音。每个可用终结点都与一个区域相关联。计划使用的终结点或区域的语音资源密钥是必需的。下面是用于了解更多信息的链接：

有关声音的完整列表，请参阅语音服务的语言和声音支持。
有关区域可用性的信息，请参阅支持语音服务的区域。
对于由世纪互联运营的 Microsoft Azure 终结点，请参阅这篇关于主权云的文章。

重要

预生成神经网络声音（在定价页上显示为“神经”）的费用各不相同。有关详细信息，请参阅语音服务定价。

在使用文本转语音 REST API 之前，请先了解，你需要在身份验证过程中完成令牌交换才能访问该服务。有关详细信息，请参阅身份验证。

获取语音列表

可以使用 tts.speech.azure.cn/cognitiveservices/voices/list 终结点来获取某个特定区域或终结点的完整语音列表。在语音列表终结点前面加上一个区域前缀，以获取该区域的语音列表。例如，若要获取 chinanorth2 区域的语音列表，请使用 https://chinanorth2.tts.speech.azure.cn/cognitiveservices/voices/list 终结点。有关所有受支持区域的列表，请参阅区域文档。

请求标头

下表列出了文本转语音请求的必需的和可选的标头：

标头	说明	必需还是可选
`Ocp-Apim-Subscription-Key`	语音资源密钥。	此标头或 `Authorization` 是必需的。
`Authorization`	前面带有单词 `Bearer` 的授权令牌。有关详细信息，请参阅身份验证。	此标头或 `Ocp-Apim-Subscription-Key` 是必需的。

请求正文

对此终结点的 GET 请求不需要正文。

示例请求

此请求只需要授权标头：

GET /cognitiveservices/voices/list HTTP/1.1

Host: chinaeast2.tts.speech.azure.cn
Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY

下面是一个 curl 命令示例：

curl --location --request GET 'https://YOUR_RESOURCE_REGION.tts.speech.azure.cn/cognitiveservices/voices/list' \
--header 'Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY'

示例响应

应收到包含所有受支持的区域设置、声音、性别、风格和其他详细信息的 JSON 正文的响应。每个语音的 WordsPerMinute 属性可用于估计输出语音的长度。此 JSON 示例显示部分结果，以说明响应的结构：

[  
    // Redacted for brevity
    {
        "Name": "Microsoft Server Speech Text to Speech Voice (en-US, JennyNeural)",
        "DisplayName": "Jenny",
        "LocalName": "Jenny",
        "ShortName": "en-US-JennyNeural",
        "Gender": "Female",
        "Locale": "en-US",
        "LocaleName": "English (United States)",
        "StyleList": [
          "assistant",
          "chat",
          "customerservice",
          "newscast",
          "angry",
          "cheerful",
          "sad",
          "excited",
          "friendly",
          "terrified",
          "shouting",
          "unfriendly",
          "whispering",
          "hopeful"
        ],
        "SampleRateHertz": "24000",
        "VoiceType": "Neural",
        "Status": "GA",
        "ExtendedPropertyMap": {
          "IsHighQuality48K": "True"
        },
        "WordsPerMinute": "152"
    },
    // Redacted for brevity
    {
        "Name": "Microsoft Server Speech Text to Speech Voice (en-US, JennyMultilingualNeural)",
        "DisplayName": "Jenny Multilingual",
        "LocalName": "Jenny Multilingual",
        "ShortName": "en-US-JennyMultilingualNeural",
        "Gender": "Female",
        "Locale": "en-US",
        "LocaleName": "English (United States)",
        "SecondaryLocaleList": [
          "de-DE",
          "en-AU",
          "en-CA",
          "en-GB",
          "es-ES",
          "es-MX",
          "fr-CA",
          "fr-FR",
          "it-IT",
          "ja-JP",
          "ko-KR",
          "pt-BR",
          "zh-cn"
        ],
        "SampleRateHertz": "24000",
        "VoiceType": "Neural",
        "Status": "GA",
        "WordsPerMinute": "190"
    },
    // Redacted for brevity
    {
        "Name": "Microsoft Server Speech Text to Speech Voice (ga-IE, OrlaNeural)",
        "DisplayName": "Orla",
        "LocalName": "Orla",
        "ShortName": "ga-IE-OrlaNeural",
        "Gender": "Female",
        "Locale": "ga-IE",
        "LocaleName": "Irish (Ireland)",
        "SampleRateHertz": "24000",
        "VoiceType": "Neural",
        "Status": "GA",
        "WordsPerMinute": "139"
    },
    // Redacted for brevity
    {
        "Name": "Microsoft Server Speech Text to Speech Voice (zh-cn, YunxiNeural)",
        "DisplayName": "Yunxi",
        "LocalName": "云希",
        "ShortName": "zh-cn-YunxiNeural",
        "Gender": "Male",
        "Locale": "zh-cn",
        "LocaleName": "Chinese (Mandarin, Simplified)",
        "StyleList": [
          "narration-relaxed",
          "embarrassed",
          "fearful",
          "cheerful",
          "disgruntled",
          "serious",
          "angry",
          "sad",
          "depressed",
          "chat",
          "assistant",
          "newscast"
        ],
        "SampleRateHertz": "24000",
        "VoiceType": "Neural",
        "Status": "GA",
        "RolePlayList": [
          "Narrator",
          "YoungAdultMale",
          "Boy"
        ],
        "WordsPerMinute": "293"
    },
    // Redacted for brevity
]

HTTP 状态代码

每个响应的 HTTP 状态代码指示成功或一般错误。

HTTP 状态代码	说明	可能的原因
200	OK	请求已成功。
400	错误的请求	必需参数缺失、为空或为 null。或者，传递给必需参数或可选参数的值无效。常见原因是某个标头过长。
401	未授权	请求未授权。确保资源密钥或令牌有效且位于正确的区域中。
429	请求太多	已超出资源允许的请求配额或速率。
502	网关错误	存在网络问题或服务器端问题。此状态也可能指示无效的标头。

将文本转换为语音

利用 cognitiveservices/v1 终结点，可以通过使用语音合成标记语言 (SSML) 将文本转换为语音。

区域和终结点

支持以下区域通过 REST API 使用文本转语音。请务必选择与语音资源区域匹配的终结点。

预生成的神经语音

使用此表来按区域或终结点确定神经网络声音的可用性：

区域	终结点
中国东部 2	`https://chinaeast2.tts.speech.azure.cn/cognitiveservices/v1`
中国北部 2	`https://chinanorth2.tts.speech.azure.cn/cognitiveservices/v1`
中国北部 3	`https://chinanorth3.tts.speech.azure.cn/cognitiveservices/v1`

请求标头

下表列出了文本转语音请求的必需的和可选的标头：

标头	说明	必需还是可选
`Authorization`	前面带有单词 `Bearer` 的授权令牌。有关详细信息，请参阅身份验证。	必需
`Content-Type`	指定所提供的文本的内容类型。接受的值：`application/ssml+xml`。	必需
`X-Microsoft-OutputFormat`	指定音频输出格式。有关接受值的完整列表，请参阅音频输出。	必需
`User-Agent`	应用程序名称。提供的值必须少于 255 个字符。	必需

请求正文

每个 POST 请求的主体将以 SSML 形式发送。利用 SSML，可以选择文本转语音功能返回的合成语音的声音和语言。有关受支持声音的完整列表，请参阅语音服务的语言和声音支持。

示例请求

此 HTTP 请求使用 SSML 指定语音和语言。如果正文长度较长，并且生成的音频超过 10 分钟，则将其截断为 10 分钟。换句话说，音频长度不能超过 10 分钟。

POST /cognitiveservices/v1 HTTP/1.1

X-Microsoft-OutputFormat: riff-24khz-16bit-mono-pcm
Content-Type: application/ssml+xml
Host: chinaeast2.tts.speech.azure.cn
Content-Length: <Length>
Authorization: Bearer [Base64 access_token]
User-Agent: <Your application name>

<speak version='1.0' xml:lang='en-US'><voice xml:lang='en-US' xml:gender='Male'
    name='en-US-ChristopherNeural'>
        I'm excited to try text to speech!
</voice></speak>

^* 对于 "Content-Length"，应使用你自己的内容长度。大多数情况下，此值由系统自动计算。

HTTP 状态代码

每个响应的 HTTP 状态代码指示成功或一般错误：

HTTP 状态代码	说明	可能的原因
200	OK	请求已成功。响应正文为音频文件。
400	错误的请求	必需参数缺失、为空或为 null。或者，传递给必需参数或可选参数的值无效。常见原因是某个标头过长。
401	未授权	请求未授权。请确保语音资源密钥或令牌有效且位于正确的区域中。
415	不支持的媒体类型	可能提供了错误的 `Content-Type` 值。 `Content-Type` 应设置为 `application/ssml+xml`。
429	请求太多	已超出资源允许的请求配额或速率。
502	网关错误	存在网络问题或服务器端问题。此状态也可能指示无效的标头。

如果 HTTP 状态为 200 OK，则响应正文包含采用所请求格式的音频文件。可以一边传输一边播放此文件，或者将其保存到缓冲区或文件中。

音频输出

支持的流式处理和非流式处理音频格式以 X-Microsoft-OutputFormat 标头的形式在每个请求中发送。每种格式都包含比特率和编码类型。语音服务支持 48 kHz、24 kHz、16 kHz 和 8 kHz 音频输出。每个预生成的神经网络声音模型在 24kHz 和高保真 48kHz 上可用。

流式处理
非流式处理

amr-wb-16000hz
audio-16khz-16bit-32kbps-mono-opus
audio-16khz-32kbitrate-mono-mp3
audio-16khz-64kbitrate-mono-mp3
audio-16khz-128kbitrate-mono-mp3
audio-24khz-16bit-24kbps-mono-opus
audio-24khz-16bit-48kbps-mono-opus
audio-24khz-48kbitrate-mono-mp3
audio-24khz-96kbitrate-mono-mp3
audio-24khz-160kbitrate-mono-mp3
audio-48khz-96kbitrate-mono-mp3
audio-48khz-192kbitrate-mono-mp3
ogg-16khz-16bit-mono-opus
ogg-24khz-16bit-mono-opus
ogg-48khz-16bit-mono-opus
raw-8khz-8bit-mono-alaw
raw-8khz-8bit-mono-mulaw
raw-8khz-16bit-mono-pcm
raw-16khz-16bit-mono-pcm
raw-16khz-16bit-mono-truesilk
raw-22050hz-16bit-mono-pcm
raw-24khz-16bit-mono-pcm
raw-24khz-16bit-mono-truesilk
raw-44100hz-16bit-mono-pcm
raw-48khz-16bit-mono-pcm
webm-16khz-16bit-mono-opus
webm-24khz-16bit-24kbps-mono-opus
webm-24khz-16bit-mono-opus

riff-8khz-8bit-mono-alaw
riff-8khz-8bit-mono-mulaw
riff-8khz-16bit-mono-pcm
riff-22050hz-16bit-mono-pcm
riff-24khz-16bit-mono-pcm
riff-44100hz-16bit-mono-pcm
riff-48khz-16bit-mono-pcm

注意

如果选择 48kHz 输出格式，则会相应地调用具有 48kHz 的高保真语音模型。合成时，可以通过向上采样或向下采样来获取除 24kHz 和 48kHz 以外的采样率，例如，44.1kHz 从 48kHz 向下采样。

如果所选语音和输出格式具有不同的比特率，则根据需要对音频重新采样。可以通过使用 Opus 编解码器来对 ogg-24khz-16bit-mono-opus 格式进行解码。

身份验证

每个请求都需要一个授权标头。下表说明了每个功能支持的标头：

受支持的授权标头	语音转文本	文本到语音转换
`Ocp-Apim-Subscription-Key`	是	是
`Authorization: Bearer`	是	是

使用 Ocp-Apim-Subscription-Key 标头时，必须仅提供资源密钥。例如：

'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'

使用 Authorization: Bearer 标头时，需要向 issueToken 终结点发出请求。在此请求中，用资源密钥交换一个有效期为 10 分钟的访问令牌。

另一种选择是使用 Microsoft Entra 身份验证，该身份验证也使用 Authorization: Bearer 标头，但使用通过 Microsoft Entra ID 颁发的令牌。请参阅使用 Microsoft Entra 身份验证。

如何获取访问令牌

若要获取访问令牌，需要通过使用 Ocp-Apim-Subscription-Key 和你的资源密钥来向 issueToken 终结点发出请求。

issueToken 终结点具有以下格式：

https://<REGION_IDENTIFIER>.api.cognitive.azure.cn/sts/v1.0/issueToken

将 <REGION_IDENTIFIER> 替换为与订阅所在区域匹配的标识符。

使用以下示例来创建访问令牌请求。

HTTP 示例

此示例是获取令牌的简单 HTTP 请求。将 YOUR_SUBSCRIPTION_KEY 替换为你的语音服务的资源密钥。如果订阅不在“中国东部 2”区域，请将 Host 标头替换为你的区域的主机名。

POST /sts/v1.0/issueToken HTTP/1.1
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
Host: chinaeast2.api.cognitive.azure.cn
Content-type: application/x-www-form-urlencoded
Content-Length: 0

响应正文包含 JSON Web 令牌 (JWT) 格式的访问令牌。

PowerShell 示例

此示例是获取访问令牌的简单 PowerShell 脚本。将 YOUR_SUBSCRIPTION_KEY 替换为你的语音服务的资源密钥。请务必使用与订阅匹配的正确区域终结点。此示例目前设置为“中国东部 2”。

$FetchTokenHeader = @{
  'Content-type'='application/x-www-form-urlencoded';
  'Content-Length'= '0';
  'Ocp-Apim-Subscription-Key' = 'YOUR_SUBSCRIPTION_KEY'
}

$OAuthToken = Invoke-RestMethod -Method POST -Uri https://chinaeast2.api.cognitive.azure.cn/sts/v1.0/issueToken
 -Headers $FetchTokenHeader

# show the token received
$OAuthToken

cURL 示例

cURL 是 Linux（及面向 Linux 的 Windows 子系统）中提供的一种命令行工具。此 cURL 命令演示如何获取访问令牌。将 YOUR_SUBSCRIPTION_KEY 替换为你的语音服务的资源密钥。请务必使用与订阅匹配的正确区域终结点。此示例目前设置为“中国东部 2”。

curl -v -X POST \
 "https://chinaeast2.api.cognitive.azure.cn/sts/v1.0/issueToken" \
 -H "Content-type: application/x-www-form-urlencoded" \
 -H "Content-Length: 0" \
 -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY"

C# 示例

此 C# 类演示如何获取访问令牌。在实例化该类时，传递你的语音服务的资源密钥。如果订阅不在“中国东部 2”区域，请更改 FetchTokenUri 的值，使之与订阅的区域匹配。

public class Authentication
{
    public static readonly string FetchTokenUri =
        "https://chinaeast2.api.cognitive.azure.cn/sts/v1.0/issueToken";
    private string subscriptionKey;
    private string token;

    public Authentication(string subscriptionKey)
    {
        this.subscriptionKey = subscriptionKey;
        this.token = FetchTokenAsync(FetchTokenUri, subscriptionKey).Result;
    }

    public string GetAccessToken()
    {
        return this.token;
    }

    private async Task<string> FetchTokenAsync(string fetchUri, string subscriptionKey)
    {
        using (var client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", subscriptionKey);
            UriBuilder uriBuilder = new UriBuilder(fetchUri);

            var result = await client.PostAsync(uriBuilder.Uri.AbsoluteUri, null);
            Console.WriteLine("Token Uri: {0}", uriBuilder.Uri.AbsoluteUri);
            return await result.Content.ReadAsStringAsync();
        }
    }
}

Python 示例

# Request module must be installed.
# Run pip install requests if necessary.
import requests

subscription_key = 'REPLACE_WITH_YOUR_KEY'


def get_token(subscription_key):
    fetch_token_url = 'https://chinaeast2.api.cognitive.azure.cn/sts/v1.0/issueToken'
    headers = {
        'Ocp-Apim-Subscription-Key': subscription_key
    }
    response = requests.post(fetch_token_url, headers=headers)
    access_token = str(response.text)
    print(access_token)

如何使用访问令牌

应将访问令牌作为 Authorization: Bearer <TOKEN> 标头发送到服务。每个访问令牌的有效期为 10 分钟。你随时可以获取新令牌，但为了最大限度地减少网络流量和延迟，建议同一令牌使用 9 分钟。

下面是向适用于短音频的语音转文本 REST API 发出的示例 HTTP 请求：

POST /cognitiveservices/v1 HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN
Host: chinaeast2.stt.speech.azure.cn
Content-type: application/ssml+xml
Content-Length: 199
Connection: Keep-Alive

// Message body here...

使用 Microsoft Entra 身份验证

要将 Microsoft Entra 身份验证与语音转文本 REST API 配合用于短音频，需要创建访问令牌。获取包含资源 ID 和 Microsoft Entra 访问令牌的访问令牌的步骤与使用语音 SDK 时的步骤相同。按照此处的步骤操作：使用 Microsoft Entra 身份验证

创建语音资源
为 Microsoft Entra 身份验证配置语音资源
获取 Microsoft Entra 访问令牌
获取语音资源 ID

获取资源 ID 和 Microsoft Entra 访问令牌后，可以按照以下格式构造实际的访问令牌：

aad#YOUR_RESOURCE_ID#YOUR_MICROSOFT_ENTRA_ACCESS_TOKEN

需要在资源 ID 和访问令牌之间包含“aad#”前缀和“#”（哈希）分隔符。

下面是向适用于短音频的语音转文本 REST API 发出的示例 HTTP 请求：

POST /cognitiveservices/v1 HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN
Host: chinanorth.stt.speech.azure.cn
Content-type: application/ssml+xml
Content-Length: 199
Connection: Keep-Alive

// Message body here...

若要详细了解 Microsoft Entra 访问令牌（包括令牌生存期），请访问 Microsoft 标识平台中的访问令牌。

后续步骤

创建 Azure 帐户

通过

文本转语音 REST API

获取语音列表

请求标头

请求正文

示例请求

示例响应

HTTP 状态代码

将文本转换为语音

区域和终结点

预生成的神经语音

请求标头

请求正文

示例请求

HTTP 状态代码

音频输出

身份验证

如何获取访问令牌

HTTP 示例

PowerShell 示例

cURL 示例

C# 示例

Python 示例

如何使用访问令牌

使用 Microsoft Entra 身份验证

后续步骤

其他资源