迁移到自定义语音 REST API（预览）

注意

此功能目前处于公开预览状态。 此预览版没有附带服务级别协议，建议不要用于生产工作负载。 某些功能可能不受支持或者受限。 有关详细信息，请参阅 Microsoft Azure 预览版补充使用条款。

自定义语音 REST API 是文本转语音 REST API 的新版本。 可以通过 API 部署和使用自定义语音模型。

在本文中，你将学习如何将代码从 v3 文本转语音 REST API 迁移到自定义语音 REST API中。

本文保留了有关 v3 版文本转语音 REST API 的信息供参考。 但进行新的开发时应使用自定义语音 REST API。

所需的更改

暂停终结点：使用自定义语音 API 暂停终结点操作来暂停终结点。 v3 版文本转语音 REST API 暂停终结点操作即将停用。

恢复终结点：使用自定义语音 API 恢复终结点操作来恢复终结点。 v3 版文本转语音 REST API 恢复终结点操作即将停用。

v3 版文本转语音 REST API 的参考文档（即将停用）

通过 REST API 暂停和恢复终结点

本部分介绍如何通过 REST API 获取、 暂停或 恢复 自定义语音终结点。

获取终结点

按终结点 ID 获取终结点。 该操作返回有关终结点的详细信息，例如模型 ID、项目 ID 和状态。

例如，可能想要跟踪暂停或恢复操作的状态进度。 使用响应有效负载中的 status 属性确定终结点的状态。

可能的 status 属性值为：

状态	说明
NotStarted	终结点未部署，不可用于语音合成。
Running	终结点正在部署或恢复的过程中，不可用于语音合成。
Succeeded	终结点处于活动状态，可用于语音合成。 终结点已部署或恢复操作成功。
Failed	终结点部署或挂起操作失败。 只能在 Speech Studio 中查看或删除终结点。
Disabling	终结点正在暂停的过程中，不可用于语音合成。
Disabled	终结点处于非活动状态，不可用于语音合成。 暂停操作成功或恢复操作失败。

提示

如果状态为 Failed 或 Disabled，请检查 properties.error 获取详细的错误消息。 但是，如果由于成功的暂停操作，状态为 Disabled，则不会有错误详细信息。

获取终结点示例

有关终结点 ID、区域和语音资源密钥参数的信息，请参阅请求参数。

HTTP 示例：

GET api/texttospeech/v3.0/endpoints/<YourEndpointId> HTTP/1.1
Ocp-Apim-Subscription-Key: YourResourceKey
Host: <YourResourceRegion>.customvoice.api.speech.microsoft.com

cURL 示例：

curl -v -X GET "https://<YourResourceRegion>.customvoice.api.speech.microsoft.com/api/texttospeech/v3.0/endpoints/<YourEndpointId>" -H "Ocp-Apim-Subscription-Key: <YourResourceKey >"

响应头示例：

Status code: 200 OK

响应正文示例：

{
  "model": {
    "id": "a92aa4b5-30f5-40db-820c-d2d57353de44"
  },
  "project": {
    "id": "ffc87aba-9f5f-4bfa-9923-b98186591a79"
  },
  "properties": {},
  "status": "Succeeded",
  "lastActionDateTime": "2019-01-07T11:36:07Z",
  "id": "e7ffdf12-17c7-4421-9428-a7235931a653",
  "createdDateTime": "2019-01-07T11:34:12Z",
  "locale": "en-US",
  "name": "Voice endpoint",
  "description": "Example for voice endpoint"
}

暂停终结点

可以暂停终结点，以限制支出和节省不使用的资源。 终结点挂起时不会产生费用。 恢复终结点时，可以在应用程序中使用相同的终结点 URL 来合成语音。

使用唯一的部署 ID 暂停终结点。 终结点状态必须为 Succeeded，才能暂停该终结点。

使用获取终结点操作来轮询并跟踪从 Succeeded 到 Disabling 并最终到 Disabled 的状态进度。

暂停终结点示例

有关终结点 ID、区域和语音资源密钥参数的信息，请参阅请求参数。

HTTP 示例：

POST api/texttospeech/v3.0/endpoints/<YourEndpointId>/suspend HTTP/1.1
Ocp-Apim-Subscription-Key: YourResourceKey
Host: <YourResourceRegion>.customvoice.api.speech.microsoft.com
Content-Type: application/json
Content-Length: 0

cURL 示例：

curl -v -X POST "https://<YourResourceRegion>.customvoice.api.speech.microsoft.com/api/texttospeech/v3.0/endpoints/<YourEndpointId>/suspend" -H "Ocp-Apim-Subscription-Key: <YourResourceKey >" -H "content-type: application/json" -H "content-length: 0"

响应头示例：

Status code: 202 Accepted

有关详细信息，请参阅响应头。

恢复终结点

恢复终结点时，可以使用在暂停之前使用的相同终结点 URL。

使用唯一的部署 ID 恢复终结点。 终结点状态必须为 Disabled，才能恢复该终结点。

使用获取终结点操作来轮询并跟踪从 Disabled 到 Running 并最终到 Succeeded 的状态进度。 如果恢复操作失败，则终结点状态将为 Disabled。

恢复终结点示例

有关终结点 ID、区域和语音资源密钥参数的信息，请参阅请求参数。

HTTP 示例：

POST api/texttospeech/v3.0/endpoints/<YourEndpointId>/resume HTTP/1.1
Ocp-Apim-Subscription-Key: YourResourceKey
Host: <YourResourceRegion>.customvoice.api.speech.microsoft.com
Content-Type: application/json
Content-Length: 0

cURL 示例：

curl -v -X POST "https://<YourResourceRegion>.customvoice.api.speech.microsoft.com/api/texttospeech/v3.0/endpoints/<YourEndpointId>/resume" -H "Ocp-Apim-Subscription-Key: <YourResourceKey >" -H "content-type: application/json" -H "content-length: 0"

响应头示例：

Status code: 202 Accepted

有关详细信息，请参阅响应头。

参数和响应代码

请求参数

可将这些请求参数与调用 REST API 一起使用。

名称	位置	必需	类型​​	说明
YourResourceRegion	路径	True	字符串	终结点关联的 Azure 区域。
YourEndpointId	路径	True	字符串	终结点的标识符。
Ocp-Apim-Subscription-Key	标头	True	字符串	终结点关联的语音资源密钥。

响应头

状态代码：202 已接受

名称	类型​​	说明
Location	字符串	可用作获取终结点的完整 URL 的终结点的位置。
Retry-After	字符串	获取终结点状态的建议重试间隔的总秒数。

HTTP 状态代码

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

HTTP 状态代码	说明	可能的原因
200	好的	请求已成功。
202	已接受	请求已接受并正在处理。
400	错误的请求	参数的值无效，或者必需参数缺失、为空或为 null。 一个常见问题是标头太长。
401	未授权	请求未授权。
429	请求过多	已超过语音资源允许的配额或请求速率。
502	错误的网关	网络或服务器端问题。 此状态也可能指示无效的标头。

后续步骤

• 部署专业语音