文本转语音 REST API

Artículo
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 帐户

Compartir a través de

文本转语音 REST API

获取语音列表

请求标头

请求正文

示例请求

示例响应

HTTP 状态代码

将文本转换为语音

区域和终结点

预生成的神经语音

请求标头

请求正文

示例请求

HTTP 状态代码

音频输出

身份验证

如何获取访问令牌

HTTP 示例

PowerShell 示例

cURL 示例

C# 示例

Python 示例

如何使用访问令牌

使用 Microsoft Entra 身份验证

后续步骤

Recursos adicionales