你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

用于文本转语音的批量合成 API

项目
09/12/2024

批量合成 API 可以异步合成大量文本输入（长文本和短文本）。发布者和音频内容平台可以批量创建长音频内容。例如：音频书籍、新闻文章和文档。批处理合成 API 可以创建超过 10 分钟的合成音频。

重要

批量合成 API 现已正式发布。长音频 API 将于 2027 年 4 月 1 日停用。有关详细信息，请参见迁移到批处理合成 API。

批处理合成 API 是异步的，因此不会实时返回合成的音频。提交要合成的文本文件，轮询状态，并在状态指示成功时下载音频输出。文本输入必须是纯文本或语音合成标记语言 (SSML) 文本。

此图高度概括了该工作流。

批处理合成 API 工作流的示意图。

提示

还可以使用语音 SDK 通过迭代文本并将其合成为区块来创建超过 10 分钟的合成音频。有关 C# 示例，请参阅 GitHub。

可以使用以下 REST API 操作进行批处理合成：

操作	方法	REST API 调用
创建批量合成	`PUT`	texttospeech/batchsyntheses/YourSynthesisId
获取批量合成	`GET`	texttospeech/batchsyntheses/YourSynthesisId
列出批量合成	`GET`	texttospeech/batchsyntheses
删除批量合成	`DELETE`	texttospeech/batchsyntheses/YourSynthesisId

有关代码示例，请参阅 GitHub。

创建批处理合成

若要提交批量合成请求，请按照以下说明构造 HTTP PUT 请求路径和正文：

设置所需的 inputKind 属性。
如果 inputKind 属性设置为“PlainText”，则还必须在 synthesisConfig 中设置 voice 属性。在下面的示例中，inputKind 设置为“SSML”，因此未设置 synthesisConfig。
（可选）可以设置 description、timeToLiveInHours 和其他属性。有关详细信息，请参阅批处理合成属性。

注意

可接受的最大 JSON 有效负载大小为 2 MB。

在路径中设置所需的 YourSynthesisId。 YourSynthesisId 必须独一无二。长度必须为 3-64，仅包含数字、字母、连字符、下划线和句点，并以字母或数字开头和结尾。

使用 URI 发出 HTTP PUT 请求，如以下示例所示。将 YourSpeechKey 替换为语音资源密钥，将 YourSpeechRegion 替换为语音资源区域，并按前面所述设置请求正文属性。

curl -v -X PUT -H "Ocp-Apim-Subscription-Key: YourSpeechKey" -H "Content-Type: application/json" -d '{
    "description": "my ssml test",
    "inputKind": "SSML",
    "inputs": [
        {
            "content": "<speak version=\"1.0\" xml:lang=\"en-US\"><voice name=\"en-US-JennyNeural\">The rainbow has seven colors.</voice></speak>"
        }
    ],
    "properties": {
        "outputFormat": "riff-24khz-16bit-mono-pcm",
        "wordBoundaryEnabled": false,
        "sentenceBoundaryEnabled": false,
        "concatenateResult": false,
        "decompressOutputFiles": false
    }
}'  "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01"

你应该会收到以下格式的响应正文：

{
  "id": "YourSynthesisId",
  "internalId": "7ab84171-9070-4d3b-88d4-1b8cc1cb928a",
  "status": "NotStarted",
  "createdDateTime": "2024-03-12T07:23:18.0097387Z",
  "lastActionDateTime": "2024-03-12T07:23:18.0097388Z",
  "inputKind": "SSML",
  "customVoices": {},
  "properties": {
    "timeToLiveInHours": 744,
    "outputFormat": "riff-24khz-16bit-mono-pcm",
    "concatenateResult": false,
    "decompressOutputFiles": false,
    "wordBoundaryEnabled": false,
    "sentenceBoundaryEnabled": false
  }
}

status 属性应从 NotStarted 状态发展为 Running，最后变更为 Succeeded 或 Failed。可以周期性调用 GET 批批处理合成 API，直到返回状态为 Succeeded 或 Failed。

获取批处理合成

若要获取批处理合成作业的状态，请使用 URI 发出 HTTP GET 请求，如以下示例所示。将 YourSpeechKey 替换为语音资源密钥，将 YourSpeechRegion 替换为语音资源区域。

curl -v -X GET "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"

你应该会收到以下格式的响应正文：

{
  "id": "YourSynthesisId",
  "internalId": "7ab84171-9070-4d3b-88d4-1b8cc1cb928a",
  "status": "Succeeded",
  "createdDateTime": "2024-03-12T07:23:18.0097387Z",
  "lastActionDateTime": "2024-03-12T07:23:18.7979669",
  "inputKind": "SSML",
  "customVoices": {},
  "properties": {
    "timeToLiveInHours": 744,
    "outputFormat": "riff-24khz-16bit-mono-pcm",
    "concatenateResult": false,
    "decompressOutputFiles": false,
    "wordBoundaryEnabled": false,
    "sentenceBoundaryEnabled": false,
    "sizeInBytes": 120000,
    "succeededAudioCount": 1,
    "failedAudioCount": 0,
    "durationInMilliseconds": 2500,
    "billingDetails": {
      "neuralCharacters": 29
    }
  },
  "outputs": {
    "result": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/29f2105f997c4bfea176d39d05ff201e/YourSynthesisId/results.zip?SAS_Token"
  }
}

从 outputs.result 中，可以下载包含音频（如 0001.wav）、摘要和调试详细信息的 ZIP 文件。有关详细信息，请参阅批处理合成结果。

列出批处理合成

若要列出语音资源的所有批处理合成作业，请使用 URI 发出 HTTP GET 请求，如以下示例所示。将 YourSpeechKey 替换为语音资源密钥，将 YourSpeechRegion 替换为语音资源区域。（可选）可以在 URL 中设置 skip 和 maxpagesize（不超过 100）查询参数。 skip 的默认值为 0，maxpagesize 的默认值为 100。

curl -v -X GET "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses?api-version=2024-04-01&skip=1&maxpagesize=2" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"

你应该会收到以下格式的响应正文：

{
  "value": [
    {
      "id": "my-job-03",
      "internalId": "5f7e9ab6-2c92-4dcb-b5ee-ec0983ee4db0",
      "status": "Succeeded",
      "createdDateTime": "2024-03-12T07:28:32.5690441Z",
      "lastActionDateTime": "2024-03-12T07:28:33.0042293",
      "inputKind": "SSML",
      "customVoices": {},
      "properties": {
        "timeToLiveInHours": 744,
        "outputFormat": "riff-24khz-16bit-mono-pcm",
        "concatenateResult": false,
        "decompressOutputFiles": false,
        "wordBoundaryEnabled": false,
        "sentenceBoundaryEnabled": false,
        "sizeInBytes": 120000,
        "succeededAudioCount": 1,
        "failedAudioCount": 0,
        "durationInMilliseconds": 2500,
        "billingDetails": {
          "neuralCharacters": 29
        }
      },
      "outputs": {
        "result": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/29f2105f997c4bfea176d39d05ff201e/my-job-03/results.zip?SAS_Token"
      }
    },
    {
      "id": "my-job-02",
      "internalId": "5577585f-4710-4d4f-aab6-162d14bd7ee0",
      "status": "Succeeded",
      "createdDateTime": "2024-03-12T07:28:29.6418211Z",
      "lastActionDateTime": "2024-03-12T07:28:30.0910306",
      "inputKind": "SSML",
      "customVoices": {},
      "properties": {
        "timeToLiveInHours": 744,
        "outputFormat": "riff-24khz-16bit-mono-pcm",
        "concatenateResult": false,
        "decompressOutputFiles": false,
        "wordBoundaryEnabled": false,
        "sentenceBoundaryEnabled": false,
        "sizeInBytes": 120000,
        "succeededAudioCount": 1,
        "failedAudioCount": 0,
        "durationInMilliseconds": 2500,
        "billingDetails": {
          "neuralCharacters": 29
        }
      },
      "outputs": {
        "result": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/29f2105f997c4bfea176d39d05ff201e/my-job-02/results.zip?SAS_Token"
      }
    }
  ],
  "nextLink": "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses?skip=3&maxpagesize=2&api-version=2024-04-01"
}

从 outputs.result 中，可以下载包含音频（如 0001.wav）、摘要和调试详细信息的 ZIP 文件。有关详细信息，请参阅批处理合成结果。

json 响应中的 value 属性列出了合成请求。此列表已分页，最大页大小为 100。根据需要提供 "nextLink" 属性以获取分页列表的下一页。

删除批处理合成

检索音频输出结果后，请删除批处理合成作业历史记录。语音服务可将批量合成历史记录最多保留 31 天，或请求 timeToLiveInHours 属性的持续时间，两者以先到者为准。自动删除的日期和时间（对于状态为“成功”或“失败”的合成作业）等于 lastActionDateTime + timeToLiveInHours 属性。

若要删除批处理合成作业，请使用 URI 发出 HTTP DELETE 请求，如以下示例所示。将 YourSynthesisId 替换为批处理合成 ID，将 YourSpeechKey 替换为语音资源密钥，将 YourSpeechRegion 替换为语音资源区域。

curl -v -X DELETE "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"

如果删除请求成功，则响应头包含 HTTP/1.1 204 No Content。

批处理合成结果

获取批处理合成作业status 为“成功”后，可以下载音频输出结果。使用 batch synthesis GET 响应的 outputs.result 属性中的 URL。

若要获取批处理合成结果文件，请使用 URI 发出 HTTP GET 请求，如以下示例所示。将 YourOutputsResultUrl 替换为 batch synthesis GET 响应的 outputs.result 属性中的 URL。将 YourSpeechKey 替换为语音资源密钥。

curl -v -X GET "YourOutputsResultUrl" -H "Ocp-Apim-Subscription-Key: YourSpeechKey" > results.zip

结果位于包含音频（如 0001.wav）、摘要和调试详细信息的 ZIP 文件中。每个文件名的前缀编号（如下所示为 [nnnn]）与创建批处理合成时使用的文本输入的顺序相同。

注意

[nnnn].debug.json 文件包含合成结果 ID 和其他可能有助于故障排除的信息。它包含的属性可能会更改，因此不应采用 JSON 格式的任何依赖项。

摘要文件包含每个文本输入的合成结果。下面是一个示例 summary.json 文件：

{
  "jobID": "7ab84171-9070-4d3b-88d4-1b8cc1cb928a",
  "status": "Succeeded",
  "results": [
    {
      "contents": [
        "<speak version=\"1.0\" xml:lang=\"en-US\"><voice name=\"en-US-JennyNeural\">The rainbow has seven colors.</voice></speak>"
      ],
      "status": "Succeeded",
      "audioFileName": "0001.wav",
      "properties": {
        "sizeInBytes": "120000",
        "durationInMilliseconds": "2500"
      }
    }
  ]
}

如果请求了句子边界数据 ("sentenceBoundaryEnabled": true)，则结果中将包含相应的 [nnnn].sentence.json 文件。同样，如果请求了字边界数据 ("wordBoundaryEnabled": true)，则结果中将包含相应的 [nnnn].word.json 文件。

下面是一个示例字数据文件，其中包含音频偏移量和持续时间（以毫秒为单位）：

[
  {
    "Text": "The",
    "AudioOffset": 50,
    "Duration": 137
  },
  {
    "Text": "rainbow",
    "AudioOffset": 200,
    "Duration": 350
  },
  {
    "Text": "has",
    "AudioOffset": 562,
    "Duration": 175
  },
  {
    "Text": "seven",
    "AudioOffset": 750,
    "Duration": 300
  },
  {
    "Text": "colors",
    "AudioOffset": 1062,
    "Duration": 625
  },
  {
    "Text": ".",
    "AudioOffset": 1700,
    "Duration": 100
  }
]

批处理合成延迟和最佳做法

在使用批处理合成生成合成语音时，请务必考虑所涉及的延迟，并遵循最佳做法来获得最佳结果。

批处理合成中的延迟

批处理合成中的延迟取决于各种因素，包括输入文本的复杂性、批处理中的输入数以及基础硬件的处理能力。

批处理合成的延迟如下所示（大约）：

50% 的合成语音输出的延迟在 10-20 秒内。
95% 的合成语音输出的延迟在 120 秒内。

最佳实践

当考虑为应用程序进行批量合成时，建议评估延迟是否符合要求。如果延迟与所需的性能一致，则可以选择批处理合成。但如果延迟不满足需求，则可以考虑使用实时 API。

HTTP 状态代码

本部分详细介绍了来自批处理合成 API 的 HTTP 响应代码和消息。

HTTP 200 OK

"HTTP 200 OK" 表示请求成功。

HTTP 201 已创建

“HTTP 201 已创建”表示已成功创建批量合成请求（通过 HTTP PUT）。

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."
  }
}

通过

用于文本转语音的批量合成 API

创建批处理合成

获取批处理合成

列出批处理合成

删除批处理合成

批处理合成结果

批处理合成延迟和最佳做法

批处理合成中的延迟

最佳实践

HTTP 状态代码

HTTP 200 OK

HTTP 201 已创建

HTTP 204 错误

HTTP 400 错误

HTTP 404 错误

HTTP 429 错误

HTTP 500 错误

HTTP 错误示例

后续步骤

反馈

其他资源