文本转语音 REST API

语音服务允许你将文本转换为合成语音，并使用 REST API 获取区域支持的语音列表。在本文中，你将了解授权选项、查询选项、如何构建请求以及如何解释响应。

Tip

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

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

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

Important

标准语音的成本各不相同。有关详细信息，请参阅文本转语音定价。

Prerequisites

若要使用文本转语音 REST API，需要：

一个 Azure 帐户。创建一个试用帐户。
Azure 门户中的语音资源。
来自您的语音资源密钥和端点页面的资源密钥和端点。

Authentication

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

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

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

'Ocp-Apim-Subscription-Key': 'YourSpeechResourceKey'

如果您将 Authorization: Bearer 与 STS 持有者令牌流程一起使用，请先向 issueToken 端点发送请求。在此请求中，将资源密钥交换为有效期为 10 分钟的访问令牌。

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

如何获取 STS 访问令牌

若要获取 STS 访问令牌，请使用 issueToken 和资源密钥向 Ocp-Apim-Subscription-Key 端点发出请求。

终结点 issueToken 采用以下格式：

https://YourResourceName.cognitiveservices.azure.cn/sts/v1.0/issueToken

将 YourResourceName 替换为你的语音资源名称。

Note

此终结点要求资源配置自定义子域。对于没有自定义域的资源，请改用区域终结点： https://<region>.api.cognitive.azure.cn/sts/v1.0/issueToken 将 <region> 替换为资源的Azure区域（例如，chinanorth2）。

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

HTTP 示例

此示例是获取令牌的简单 HTTP 请求。将 YourSpeechResourceKey 替换为语音服务的资源密钥。将 YourResourceName 替换为你的语音资源名称。

POST /sts/v1.0/issueToken HTTP/1.1
Ocp-Apim-Subscription-Key: YourSpeechResourceKey
Host: YourResourceName.cognitiveservices.azure.cn
Content-type: application/x-www-form-urlencoded
Content-Length: 0

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

PowerShell 示例

此示例是一个简单的 PowerShell 脚本，用于获取访问令牌。将 YourSpeechResourceKey 替换为语音服务的资源密钥。将 YourResourceName 替换为你的语音资源名称。

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

$OAuthToken = Invoke-RestMethod -Method POST `
    -Uri https://YourResourceName.cognitiveservices.azure.cn/sts/v1.0/issueToken `
    -Headers $FetchTokenHeader

# show the token received
$OAuthToken

cURL 示例

cURL 是 Linux（及面向 Linux 的 Windows 子系统）中提供的一种命令行工具。此 cURL 命令演示如何获取访问令牌。将 YourSpeechResourceKey 替换为语音服务的资源密钥。将 YourResourceName 替换为你的语音资源名称。

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

C# 示例

此 C# 类演示如何获取访问令牌。在实例化该类时，传递你的语音服务的资源密钥。将 YourResourceName 替换为你的语音资源名称。

public class Authentication
{
    public static readonly string FetchTokenUri =
        "https://YourResourceName.cognitiveservices.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://YourResourceName.cognitiveservices.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 分钟。

Important

持有者令牌的作用范围仅限于签发该令牌的端点。从 YourResourceName.cognitiveservices.azure.cn 获取的令牌仅适用于对该主机的请求。来自 <region>.api.cognitive.azure.cn 的令牌仅可用于区域性语音终结点。如果您在使用 Bearer 令牌时收到 401 错误，请改为将 Ocp-Apim-Subscription-Key 与您的资源密钥一起使用，因为这种方式适用于所有终结点格式。

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

POST /cognitiveservices/v1 HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN
Host: YourResourceName.cognitiveservices.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 身份验证

创建用于语音的 AI 服务资源
为 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: YourResourceName.cognitiveservices.azure.cn
Content-type: application/ssml+xml
Content-Length: 199
Connection: Keep-Alive

// Message body here...

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

获取语音列表

可以使用 Speech 资源终结点获取完整的语音列表。将 /tts/cognitiveservices/voices/list 路径与资源终结点一起使用。例如，使用 https://YourResourceName.cognitiveservices.azure.cn/tts/cognitiveservices/voices/list 终结点。有关所有受支持区域的列表，请参阅区域文档。

Note

预览版中的语音和样式仅在区域子集中可用。有关支持公共预览版中语音和样式的区域的当前列表，请参阅语音服务区域表。

请求标头

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

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

请求主体

对此终结点的请求不需要 GET 主体。

示例请求

此请求只需要授权标头：

GET /tts/cognitiveservices/voices/list HTTP/1.1

Host: YourResourceName.cognitiveservices.azure.cn
Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY

下面是一个 curl 命令示例：

curl --location --request GET 'https://YourResourceName.cognitiveservices.azure.cn/tts/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": "48000",
        "VoiceType": "Neural",
        "Status": "GA",
        "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": "48000",
        "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": "48000",
        "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": "48000",
        "VoiceType": "Neural",
        "Status": "GA",
        "RolePlayList": [
          "Narrator",
          "YoungAdultMale",
          "Boy"
        ],
        "WordsPerMinute": "293"
    },
    // Redacted for brevity
]

HTTP 状态代码

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

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

将文本转换为语音

终结点 cognitiveservices/v1 允许使用语音合成标记语言（SSML）将文本转换为语音。

区域和终结点

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

标准语音

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

Region	终结点
中国东部 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`

请求标头

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

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

请求主体

每个 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: YourResourceName.cognitiveservices.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	好的	请求成功。响应主体是音频文件。
400	错误的请求	必需参数缺失、为空或为 null。或者，传递给必需或可选参数的值无效。一个常见原因是标头太长。
401	Unauthorized	该请求未经授权。请确保语音资源密钥或令牌有效且位于正确的区域中。
415	不支持的媒体类型	可能提供了错误的 `Content-Type` 值。 `Content-Type` 应设置为 `application/ssml+xml`.
429	请求过多	已超出资源允许的请求配额或速率。
502	网关错误	存在网络或服务器端问题。此状态也可能表示标头无效。
503	服务不可用	由于各种原因，服务器端出现问题。

如果 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
g722-16khz-64kbps
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

Note

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

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

后续步骤

创建 Azure 帐户

Last updated on 2026-09-14

文本转语音 REST API

Prerequisites

Authentication

如何获取 STS 访问令牌

HTTP 示例

PowerShell 示例

cURL 示例

C# 示例

Python示例

如何使用访问令牌

使用 Microsoft Entra 身份验证

获取语音列表

请求标头

请求主体

示例请求

示例响应

HTTP 状态代码

将文本转换为语音

区域和终结点

标准语音

请求标头

请求主体

示例请求

HTTP 状态代码

音频输出

后续步骤

Recursos adicionais