カスタム音声 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、リージョン、Speech リソース キーのパラメーターについては、要求パラメーターに関するページを参照してください。

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、リージョン、Speech リソース キーのパラメーターについては、要求パラメーターに関するページを参照してください。

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、リージョン、Speech リソース キーのパラメーターについては、要求パラメーターに関するページを参照してください。

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	ひも	エンドポイントが関連付けられている Speech リソース キー。

応答ヘッダー

状態コード: 202 Accepted

名前	タイプ	説明
Location	ひも	エンドポイントを取得する詳細な URL として使用できるエンドポイントの場所。
Retry-After	ひも	エンドポイントの状態を取得するために再試行する推奨間隔の秒数。

HTTP 状態コード

各応答の HTTP 状態コードは、成功または一般的なエラーを示します。

HTTP 状態コード	説明	考えられる理由
200	[OK]	要求は成功しました。
202	受け入れられた	要求が受け入れられ、処理されています。
400	正しくない要求	パラメーターの値が無効であるか、必須パラメーターがないか、空、または null です。 よくある問題として、ヘッダーが長すぎることがあります。
401	権限がありません	要求は承認されません。
429	要求が多すぎます	使用中の Speech リソースで許可されている要求のクォータまたは速度を超えています。
502	無効なゲートウェイ	ネットワークまたはサーバー側の問題です。 この状態コードは、無効なヘッダーを示している可能性があります。

次のステップ

• プロの音声をデプロイする