你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
文本转语音的批处理合成属性
重要
批量合成 API 现已正式发布。 长音频 API 将于 2027 年 4 月 1 日停用。 有关详细信息，请参见迁移到批处理合成 API。
批量合成 API 可以异步合成大量文本输入（长文本和短文本）。 发布者和音频内容平台可以批量创建长音频内容。 例如：音频书籍、新闻文章和文档。 批处理合成 API 可以创建超过 10 分钟的合成音频。
创建新的批处理合成作业时，需要 JSON 格式的某些属性。 其他属性为可选。 批处理合成响应还包括其他属性，用于提供有关合成状态和结果的信息。 例如，outputs.result 属性包含批处理合成结果文件及其音频输出和日志的位置。
批处理合成属性
下表描述了批处理合成属性。
| 属性 | 说明 |
|---|---|
createdDateTime |
创建批处理合成作业的日期和时间。 此属性为只读。 |
customVoices |
自定义语音名称及其部署 ID 的映射。 例如： "customVoices": {"your-custom-voice-name": "502ac834-6537-4bc3-9fd6-140114daa66d"}可以在 synthesisConfig.voice（当 inputKind 设置为 "PlainText" 时）或在 inputs（当 inputKind 设置为 "SSML" 时）的 SSML 文本中使用语音名称。此属性是使用自定义语音所必需的。 如果尝试使用此处未定义的自定义语音，服务将返回错误。 |
description |
批处理合成的说明。 此属性是可选的。 |
id |
传入路径的批量合成作业 ID。 此属性在路径中是必需项。 |
inputs |
要合成的纯文本或 SSML。 当 inputKind 设置为 "PlainText" 时，请提供纯文本，如下所示："inputs": [{"text": "The rainbow has seven colors."}]。 当 inputKind 设置为 "SSML" 时，请以语音合成标记语言 (SSML) 提供文本，如下所示："inputs": [{"text": "<speak version='\''1.0'\'' xml:lang='\''en-US'\''><voice xml:lang='\''en-US'\'' xml:gender='\''Female'\'' name='\''en-US-AvaMultilingualNeural'\''>The rainbow has seven colors.</voice></speak>"}]。如果需要多个音频输出文件，则最多包含 1,000 个文本对象。 下面是应合成为两个音频输出文件的示例输入文本： "inputs": [{"text": "synthesize this to a file"},{"text": "synthesize this to another file"}]。 但是，如果 properties.concatenateResult 属性设置为 true，则每个合成结果会写入同一音频输出文件。对于新段落，不需要单独的文本输入。 在其中（最多 1,000 个）的任何文本输入中，可以使用“\r\n”（换行符）字符串指定新段落。 下面是包含两个段落的示例输入文本，这些段落应合成为同一音频输出文件： "inputs": [{"text": "synthesize this to a file\r\nsynthesize this to another paragraph in the same file"}]没有段落限制，但 JSON 有效负载的最大大小（包括所有文本输入和其他属性）为 2 MB。 创建新的批处理合成作业时，此属性是必需的。 获取合成作业时，响应中不包含此属性。 |
internalId |
内部批量合成作业 ID。 此属性为只读。 |
lastActionDateTime |
status 属性值更改的最新日期和时间。此属性为只读。 |
outputs.result |
包含音频输出和日志的批处理合成结果文件的位置。 此属性为只读。 |
properties |
一组定义的可选批处理合成配置设置。 |
properties.sizeInBytes |
音频输出大小（以字节为单位）。 此属性为只读。 |
properties.billingDetails |
按 customNeuralCharacters 语音与 neuralCharacters（预生成）语音处理和计费的字数。此属性为只读。 |
properties.concatenateResult |
确定是否要连接结果。 默认情况下，此可选 bool 值（“true”或“false”）为“false”。 |
properties.decompressOutputFiles |
确定是否解压缩目标容器中的合成结果文件。 仅当设置了 destinationContainerUrl 属性时，才能设置此属性。 默认情况下，此可选 bool 值（“true”或“false”）为“false”。 |
properties.destinationContainerUrl |
批处理合成结果可以存储在可写 Azure 容器中。 如果未指定具有共享访问签名 (SAS) 令牌的容器 URI，则语音服务会将结果存储在由 Microsoft 管理的容器中。 不支持具有存储访问策略的 SAS。 删除合成作业时，结果数据也会被删除。 获取合成作业时，响应中不包含此可选属性。 |
properties.destinationPath |
可存储批量合成结果的前缀路径。 如果未指定前缀路径，则默认前缀路径为 YourSpeechResourceId/YourSynthesisId。仅当设置了 destinationContainerUrl 属性时，才能设置此可选属性。 |
properties.durationInMilliseconds |
音频输出持续时间（以毫秒为单位）。 此属性为只读。 |
properties.failedAudioCount |
音频输出的批处理合成输入计数失败。 此属性为只读。 |
properties.outputFormat |
音频输出格式。 有关接受的值的信息，请参阅音频输出格式。 默认输出格式为 riff-24khz-16bit-mono-pcm。 |
properties.sentenceBoundaryEnabled |
确定是否生成句子边界数据。 默认情况下，此可选 bool 值（“true”或“false”）为“false”。如果请求了句子边界数据，则结果数据 ZIP 文件中会包含相应的 [nnnn].sentence.json 文件。 |
properties.succeededAudioCount |
音频输出的批处理合成输入计数成功。 此属性为只读。 |
properties.timeToLiveInHours |
创建合成作业后的持续时间（以小时为单位），此时将自动删除合成结果。 默认情况下，此可选设置为 744（31 天）。 最长生存时间为 31 天。 自动删除的日期和时间（对于状态为“成功”或“失败”的合成作业）等于 lastActionDateTime + timeToLiveInHours 属性。除此之外，可以调用 delete 合成方法来更快地删除作业。 |
properties.wordBoundaryEnabled |
确定是否生成字边界数据。 默认情况下，此可选 bool 值（“true”或“false”）为“false”。如果请求了字边界数据，则相应的 [nnnn].word.json 文件会包含在结果数据 ZIP 文件中。 |
status |
批处理合成处理状态。 状态应从“未启动”进展为“正在运行”，最后变为“成功”或“失败”。 此属性为只读。 |
synthesisConfig |
用于批处理合成纯文本的配置设置。 此属性仅在 inputKind 设置为 "PlainText" 时适用。 |
synthesisConfig.backgroundAudio |
每个音频输出的背景音频。 此可选属性仅在 inputKind 设置为 "PlainText" 时适用。 |
synthesisConfig.backgroundAudio.fadein |
背景音频淡入的持续时间，以毫秒为单位。 默认值为 0，即，不淡入。 接受的值：0 到 10000（含）。有关信息，请参阅语音合成标记语言 (SSML) 文档中添加背景音频下的属性表。 无效值会被忽略。 此可选属性仅在 inputKind 设置为 "PlainText" 时适用。 |
synthesisConfig.backgroundAudio.fadeout |
背景音频淡出的持续时间，以毫秒为单位。 默认值为 0，即，不淡出。接受的值：0 到 10000（含）。有关信息，请参阅语音合成标记语言 (SSML) 文档中添加背景音频下的属性表。 无效值会被忽略。 此可选属性仅在 inputKind 设置为 "PlainText" 时适用。 |
synthesisConfig.backgroundAudio.src |
背景音频文件的 URI 位置。 有关信息，请参阅语音合成标记语言 (SSML) 文档中添加背景音频下的属性表。 无效值会被忽略。 设置 synthesisConfig.backgroundAudio 时，此属性是必需的。 |
synthesisConfig.backgroundAudio.volume |
背景音频文件的音量。 接受的值：0 到 100（含）。 默认值为 1。有关信息，请参阅语音合成标记语言 (SSML) 文档中添加背景音频下的属性表。 无效值会被忽略。 此可选属性仅在 inputKind 设置为 "PlainText" 时适用。 |
synthesisConfig.pitch |
音频输出的音调。 有关接受的值的信息，请参阅语音合成标记语言 (SSML) 文档中的调整韵律表。 无效值会被忽略。 此可选属性仅在 inputKind 设置为 "PlainText" 时适用。 |
synthesisConfig.rate |
音频输出的速率。 有关接受值的信息，请参阅语音合成标记语言 (SSML) 文档中的调整韵律表。 无效值会被忽略。 此可选属性仅在 inputKind 设置为 "PlainText" 时适用。 |
synthesisConfig.role |
对于某些声音，你可以调整说话角色扮演。 声音可以模仿不同的年龄和性别，但声音名称不会更改。 例如，男性语音可以提高音调和改变语调来模拟女性语音，但语音名称不会更改。 如果角色缺失或不受声音的支持，则会忽略此属性。 有关每个语音的可用样式的信息，请参阅语音风格和角色。 此可选属性仅在 inputKind 设置为 "PlainText" 时适用。 |
synthesisConfig.speakerProfileId |
个人声音的说话人配置文件 ID。 有关可用的个人声音基础模型名称的信息，请参阅集成个人声音。 有关如何获取说话人配置文件 ID 的信息，请参阅语言和语音支持。 当 inputKind 设置为 "PlainText" 时，此属性是必需的。 |
synthesisConfig.style |
对于某些语音，你可以调整说话风格来表达不同情绪，例如，高兴、同情和冷静。 可以针对不同场景（例如，客户服务、新闻广播和语音助理）优化声音。 有关每个语音的可用样式的信息，请参阅语音风格和角色。 此可选属性仅在设置 synthesisConfig.style 时适用。 |
synthesisConfig.styleDegree |
讲话风格的强度。 可以指定更强或更柔和的风格，使语音更具表现力或更柔和。 可接受值的范围为：0.01 到 2（含）。 默认值为 1，表示预定义的风格强度。 最小单位为 0.01，表示略倾向于目标风格。 值为 2 表示是默认风格强度的两倍。 如果风格程度缺失或不受声音的支持，则会忽略此属性。 有关每个语音的可用样式的信息，请参阅语音风格和角色。 此可选属性仅在 inputKind 设置为 "PlainText" 时适用。 |
synthesisConfig.voice |
说出音频输出内容的语音。 有关可用的预生成神经网络声音的信息，请参阅语言和语音支持。 若要使用自定义语音，必须在 customVoices 属性中指定有效的自定义语音和部署 ID 映射。 若要使用个人声音，需要指定 synthesisConfig.speakerProfileId 属性。 当 inputKind 设置为 "PlainText" 时，此属性是必需的。 |
synthesisConfig.volume |
音频输出的音量。 有关接受值的信息，请参阅语音合成标记语言 (SSML) 文档中的调整韵律表。 无效值会被忽略。 此可选属性仅在 inputKind 设置为 "PlainText" 时适用。 |
inputKind |
指示 inputs 文本属性应为纯文本还是 SSML。 可能的不区分大小写的值为“PlainText”和“SSML”。 当 inputKind 设置为 "PlainText" 时，还必须设置 synthesisConfig 语音属性。此属性是必需项。 |
批处理合成延迟和最佳做法
在使用批处理合成生成合成语音时，请务必考虑所涉及的延迟，并遵循最佳做法来获得最佳结果。
批处理合成中的延迟
批处理合成中的延迟取决于各种因素，包括输入文本的复杂性、批处理中的输入数以及基础硬件的处理能力。
批处理合成的延迟如下所示（大约）：
50% 的合成语音输出的延迟在 10-20 秒内。
95% 的合成语音输出的延迟在 120 秒内。
最佳实践
当考虑为应用程序进行批量合成时，建议评估延迟是否符合要求。 如果延迟与所需的性能一致，则可以选择批处理合成。 但如果延迟不满足需求，则可以考虑使用实时 API。
HTTP 状态代码
本部分详细介绍了来自批处理合成 API 的 HTTP 响应代码和消息。
HTTP 200 OK
"HTTP 200 OK" 表示请求成功。
HTTP 201 已创建
“HTTP 201 已创建”表示创建批处理合成请求（通过 HTTP POST）成功。
HTTP 204 错误
“HTTP 204 错误" 指示请求成功，但资源不存在。 例如：
- 尝试获取或删除不存在的合成作业。
- 已成功删除合成作业。
HTTP 400 错误
下面是可能导致 400 错误的示例：
outputFormat不受支持或无效。 提供有效的格式值，或将outputFormat留空以使用默认设置。- 请求的文本输入数超出了 10,000 这一限制。
- 你尝试使用的是无效的部署 ID 或未成功部署的自定义语音。 确保语音资源有权访问自定义语音，并已成功部署自定义语音。 还必须确保批处理合成请求中的
{"your-custom-voice-name": "your-deployment-ID"}映射正确。 - 你尝试使用 F0 语音资源，但该区域仅支持（标准）语音资源定价层。
HTTP 404 错误
找不到指定的实体。 请确保合成 ID 正确。
HTTP 429 错误
最近的请求太多。 每个客户端应用程序每 10 秒最多可以为每个语音资源提交 100 个请求。 减少每秒的请求数。
HTTP 500 错误
"HTTP 500 内部服务器错误" 指示请求失败。 响应正文包含错误消息。
HTTP 错误示例
下面是导致 HTTP 400 错误的示例请求，因为创建作业需要 inputs 属性。
curl -v -X PUT -H "Ocp-Apim-Subscription-Key: YourSpeechKey" -H "Content-Type: application/json" -d '{
"inputKind": "SSML"
}' "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01"
在这种情况下，响应头会包含 HTTP/1.1 400 Bad Request。
响应正文类似于以下 JSON 示例：
{
"error": {
"code": "BadRequest",
"message": "The inputs is required."
}
}