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

用于文本转语音的批处理合成 API(预览版)

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

重要

批处理合成 API 目前为公共预览版。 一旦正式发布,长音频 API 将弃用。 有关详细信息,请参见迁移到批处理合成 API

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

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

Diagram of the Batch Synthesis API workflow.

提示

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

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

操作 方法 REST API 调用
创建批处理合成 POST texttospeech/3.1-preview1/batchsynthesis
获取批处理合成 GET texttospeech/3.1-preview1/batchsynthesis/{id}
列出批处理合成 GET texttospeech/3.1-preview1/batchsynthesis
删除批处理合成 DELETE texttospeech/3.1-preview1/batchsynthesis/{id}

有关代码示例,请参阅 GitHub

创建批处理合成

若要提交批处理合成请求,请按照以下说明构造 HTTP POST 请求正文:

  • 设置所需的 textType 属性。
  • 如果 textType 属性设置为“PlainText”,则还必须在 synthesisConfig 中设置 voice 属性。 在下面的示例中,textType 设置为“SSML”,因此未设置 speechSynthesis
  • 设置所需的 displayName 属性。 选择稍后可以引用的名称。 显示名称不必是唯一的。
  • (可选)可以设置 descriptiontimeToLive 和其他属性。 有关详细信息,请参阅批处理合成属性

注意

将接受的最大 JSON 有效负载大小为 500 KB。 每个语音资源最多可以有 200 个并发运行的批处理合成作业。

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

curl -v -X POST -H "Ocp-Apim-Subscription-Key: YourSpeechKey" -H "Content-Type: application/json" -d '{
    "displayName": "batch synthesis sample",
    "description": "my ssml test",
    "textType": "SSML",
    "inputs": [
        {
            "text": "<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.customvoice.api.speech.microsoft.com/api/texttospeech/3.1-preview1/batchsynthesis"

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

{
  "textType": "SSML",
  "synthesisConfig": {},
  "customVoices": {},
  "properties": {
    "timeToLive": "P31D",
    "outputFormat": "riff-24khz-16bit-mono-pcm",
    "concatenateResult": false,
    "decompressOutputFiles": false,
    "wordBoundaryEnabled": false,
    "sentenceBoundaryEnabled": false
  },
  "lastActionDateTime": "2022-11-16T15:07:04.121Z",
  "status": "NotStarted",
  "id": "1e2e0fe8-e403-417c-a382-b55eb2ea943d",
  "createdDateTime": "2022-11-16T15:07:04.121Z",
  "displayName": "batch synthesis sample",
  "description": "my ssml test"
}

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

获取批处理合成

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

curl -v -X GET "https://YourSpeechRegion.customvoice.api.speech.microsoft.com/api/texttospeech/3.1-preview1/batchsynthesis/YourSynthesisId" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"

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

{
    "textType": "SSML",
    "synthesisConfig": {},
    "customVoices": {},
    "properties": {
      "audioSize": 100000,
      "durationInTicks": 31250000,
      "succeededAudioCount": 1,
      "failedAudioCount": 0,
      "duration": "PT3.125S",
      "billingDetails": {
        "customNeural": 0,
        "neural": 33
      },
      "timeToLive": "P31D",
      "outputFormat": "riff-24khz-16bit-mono-pcm",
      "concatenateResult": false,
      "decompressOutputFiles": false,
      "wordBoundaryEnabled": false,
      "sentenceBoundaryEnabled": false
    },
    "outputs": {
      "result": "https://cvoiceprodeus.blob.core.windows.net/batch-synthesis-output/41b83de2-380d-45dc-91af-722b68cfdc8e/results.zip?SAS_Token"
    },
    "lastActionDateTime": "2022-11-05T14:00:32.523Z",
    "status": "Succeeded",
    "id": "41b83de2-380d-45dc-91af-722b68cfdc8e",
    "createdDateTime": "2022-11-05T14:00:31.523Z",
    "displayName": "batch synthesis sample",
    "description": "my test"
  }

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

列出批处理合成

若要列出语音资源的所有批处理合成作业,请使用 URI 发出 HTTP GET 请求,如以下示例所示。 将 YourSpeechKey 替换为语音资源密钥,将 YourSpeechRegion 替换为语音资源区域。 (可选)可以在 URL 中设置 skiptop(页面大小)查询参数。 skip 的默认值为 0,top 的默认值为 100。

curl -v -X GET "https://YourSpeechRegion.customvoice.api.speech.microsoft.com/api/texttospeech/3.1-preview1/batchsynthesis?skip=0&top=2" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"

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

{
  "values": [
    {
      "textType": "SSML",
      "synthesisConfig": {},
      "customVoices": {},
      "properties": {
        "audioSize": 100000,
        "durationInTicks": 31250000,
        "succeededAudioCount": 1,
        "failedAudioCount": 0,
        "duration": "PT3.125S",
        "billingDetails": {
          "customNeural": 0,
          "neural": 33
        },
        "timeToLive": "P31D",
        "outputFormat": "riff-24khz-16bit-mono-pcm",
        "concatenateResult": false,
        "decompressOutputFiles": false,
        "wordBoundaryEnabled": false,
        "sentenceBoundaryEnabled": false
      },
      "outputs": {
        "result": "https://cvoiceprodeus.blob.core.windows.net/batch-synthesis-output/41b83de2-380d-45dc-91af-722b68cfdc8e/results.zip?SAS_Token"
      },
      "lastActionDateTime": "2022-11-05T14:00:32.523Z",
      "status": "Succeeded",
      "id": "41b83de2-380d-45dc-91af-722b68cfdc8e",
      "createdDateTime": "2022-11-05T14:00:31.523Z",
      "displayName": "batch synthesis sample",
      "description": "my test"
    }
    {
      "textType": "PlainText",
      "synthesisConfig": {
        "voice": "en-US-JennyNeural",
        "style": "chat",
        "rate": "+30.00%",
        "pitch": "x-high",
        "volume": "80"
      },
      "customVoices": {},
      "properties": {
        "audioSize": 79384,
        "durationInTicks": 24800000,
        "succeededAudioCount": 1,
        "failedAudioCount": 0,
        "duration": "PT2.48S",
        "billingDetails": {
          "customNeural": 0,
          "neural": 33
        },
        "timeToLive": "P31D",
        "outputFormat": "riff-24khz-16bit-mono-pcm",
        "concatenateResult": false,
        "decompressOutputFiles": false,
        "wordBoundaryEnabled": false,
        "sentenceBoundaryEnabled": false
      },
      "outputs": {
        "result": "https://cvoiceprodeus.blob.core.windows.net/batch-synthesis-output/38e249bf-2607-4236-930b-82f6724048d8/results.zip?SAS_Token"
      },
      "lastActionDateTime": "2022-11-05T18:52:23.210Z",
      "status": "Succeeded",
      "id": "38e249bf-2607-4236-930b-82f6724048d8",
      "createdDateTime": "2022-11-05T18:52:22.807Z",
      "displayName": "batch synthesis sample",
      "description": "my test"
    },
  ],
  // The next page link of the list of batch synthesis.
  "@nextLink": "https://{region}.customvoice.api.speech.microsoft.com/api/texttospeech/3.1-preview1/batchsynthesis?skip=0&top=2"
} 

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

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

删除批处理合成

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

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

curl -v -X DELETE "https://YourSpeechRegion.customvoice.api.speech.microsoft.com/api/texttospeech/3.1-preview1/batchsynthesis/YourSynthesisId" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"

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

批处理合成结果

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

若要获取批处理合成结果文件,请使用 URI 发出 HTTP GET 请求,如以下示例所示。 将 YourOutputsResultUrl 替换为 获取批处理合成 响应的 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":  "41b83de2-380d-45dc-91af-722b68cfdc8e",
  "status":  "Succeeded",
  "results":  [
    {
      "texts":  [
        "<speak version='1.0' xml:lang='en-US'>\n\t\t\t\t<voice name='en-US-JennyNeural'>\n\t\t\t\t\tThe rainbow has seven colors.\n\t\t\t\t</voice>\n\t\t\t</speak>"
      ],
      "status":  "Succeeded",
      "billingDetails":  {
        "CustomNeural":  "0",
        "Neural":  "33"
      },
      "audioFileName":  "0001.wav",
      "properties":  {
        "audioSize":  "100000",
        "duration":  "PT3.1S",
        "durationInTicks":  "31250000"
      }
    }
  ]
}

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

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

[
  {
    "Text": "the",
    "AudioOffset": 38,
    "Duration": 153
  },
  {
    "Text": "rainbow",
    "AudioOffset": 201,
    "Duration": 326
  },
  {
    "Text": "has",
    "AudioOffset": 567,
    "Duration": 96
  },
  {
    "Text": "seven",
    "AudioOffset": 673,
    "Duration": 96
  },
  {
    "Text": "colors",
    "AudioOffset": 778,
    "Duration": 451
  },
]

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

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

批处理合成中的延迟

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

批处理合成的延迟如下所示(大约):

  • 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 留空以使用默认设置。
  • 请求的文本输入数超出了 1,000 个的限制。
  • top 查询参数超出 100 个的限额。
  • 你尝试使用的是无效的部署 ID 或未成功部署的自定义语音。 确保语音资源有权访问自定义语音,并已成功部署自定义语音。 还必须确保批处理合成请求中的 {"your-custom-voice-name": "your-deployment-ID"} 映射正确。
  • 你已尝试删除尚未启动或尚未完成运行的批量合成作业。 只能删除状态为“成功”或“失败”的批处理合成作业。
  • 你尝试使用 F0 语音资源,但该区域仅支持(标准)语音资源定价层。
  • 你尝试创建一个新的批处理合成作业,该作业将超过 200 个活动作业的限额。 每个语音资源最多可以有 200 个没有“成功”或“失败”状态的批处理合成作业。

HTTP 404 错误

找不到指定的实体。 请确保合成 ID 正确。

HTTP 429 错误

最近的请求太多。 每个客户端应用程序每 5 秒最多可以为每个语音资源提交 50 个请求。 减少每秒的请求数。

可以通过 HTTP 标头检查速率限制和剩余配额,如以下示例所示:

X-RateLimit-Limit: 50
X-RateLimit-Remaining: 49
X-RateLimit-Reset: 2022-11-11T01:49:43Z

HTTP 500 错误

"HTTP 500 内部服务器错误" 指示请求失败。 响应正文包含错误消息。

HTTP 错误示例

下面是导致 HTTP 400 错误的示例请求,因为 top 查询参数设置为大于 100 的值。

curl -v -X GET "https://YourSpeechRegion.customvoice.api.speech.microsoft.com/api/texttospeech/3.1-preview1/batchsynthesis?skip=0&top=200" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"

在这种情况下,响应标头将包含 HTTP/1.1 400 Bad Request

响应正文类似于以下 JSON 示例:

{
  "code": "InvalidRequest",
  "message": "The top parameter should not be greater than 100.",
  "innerError": {
    "code": "InvalidParameter",
    "message": "The top parameter should not be greater than 100."
  }
}

后续步骤