テキスト読み上げ用のバッチ合成 API

[アーティクル]
09/12/2024

バッチ合成 API を使用すると、大量のテキスト入力をその長短にかかわらず非同期的に合成できます。パブリッシャーとオーディオコンテンツプラットフォームは、長い音声コンテンツをバッチで作成できます。たとえば、オーディオブック、ニュース記事、ドキュメントなどです。 10 分を超える合成音声をバッチ合成 API で作成できます。

重要

バッチ合成 API は一般提供されています。 Long Audio API は、2027 年 4 月 1 日に廃止されます。詳細については、バッチ合成 API への移行に関する記事を参照してください。

バッチ合成 API は非同期であり、合成された音声をリアルタイムでは返しません。合成するテキストファイルを送信し、状態をポーリングして、状態で成功が示されたときにオーディオ出力をダウンロードします。テキスト入力は、プレーンテキストまたは SSML (音声合成マークアップ言語) テキストである必要があります。

次の図は、ワークフローの概要を示しています。

バッチ合成 API ワークフローの図。

ヒント

Speech SDK を使い、テキストを反復処理してチャンクで合成することにより、10 分より長い合成音声を作ることもできます。 C# の例については、GitHub をご覧ください。

バッチ合成には、次の REST API 操作を使用できます。

操作	Method	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 などのプロパティを設定することもできます。詳細については、「バッチ合成のプロパティ」を参照してください。

Note

許容される最大 JSON ペイロードサイズは 2 メガバイトです。

パス内に必須の YourSynthesisId を設定します。 YourSynthesisId は一意である必要があります。 3 から 64 文字の長さにする必要があり、数字、文字、ハイフン、アンダースコア、ドットのみを含み、先頭と末尾は文字または数字にします。

次のの例に示すように、URI を使用して HTTP PUT 要求を行います。 YourSpeechKey は実際の Speech リソースキーに、YourSpeechRegion は実際の Speech リソースリージョンに置き換えたうえで、前述のように要求本文のプロパティを設定してください。

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 へと推移します。 Succeeded と Failed のどちらかの状態が返されるまで、GET バッチ合成 API を定期的に呼び出すことができます。

バッチ合成を取得する

バッチ合成ジョブの状態を取得するには、以下の例に示した 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"
  }
}

音声 (0001.wav など)、概要、デバッグの詳細を含んだ ZIP ファイルを outputs.result からダウンロードできます。詳細については、「バッチ合成の結果」を参照してください。

バッチ合成を一覧表示する

Speech リソースのすべてのバッチ合成ジョブを一覧表示するには、以下の例に示したように、URI を使用して HTTP GET 要求を行います。 YourSpeechKey は Speech リソースのキーに、YourSpeechRegion は Speech リソースのリージョンに置き換えます。 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"
}

合成要求は、json 応答の value プロパティにリストされます。一覧は改ページ調整され、最大ページサイズは 100 です。ページ分割されたリストの後続ページを取得するための "nextLink" プロパティが必要に応じて提供されます。

バッチ合成を削除する

音声出力の結果を取得したらバッチ合成のジョブ履歴を削除します。音声サービスによってバッチ合成履歴が保持される期間は、31 日間または要求の timeToLiveInHours プロパティの期間のどちらか短い方となります。 "Succeeded" または "Failed" 状態の合成ジョブでは、自動削除の日時は lastActionDateTime + timeToLiveInHours プロパティと等しくなります。

バッチ合成ジョブを取得するには、以下の例に示した URI を使用して HTTP DELETE 要求を行います。 YourSynthesisId をバッチ合成 ID に置き換え、YourSpeechKey を Speech リソースキーに置き換えて、YourSpeechRegion を Speech リソースリージョンに置き換えます。

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 が "Succeeded" であるバッチ合成ジョブを取得したら、音声出力の結果をダウンロードできます。バッチ合成 GET の応答の outputs.result プロパティから得られる URL を使用します。

バッチ合成の結果ファイルを取得するには、以下の例に示した URI を使用して HTTP GET 要求を行います。 YourOutputsResultUrl は、バッチ合成 GET の応答の outputs.result プロパティから得られる URL に置き換えます。 YourSpeechKey をSpeech リソースキーに置き換えます。

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

結果は、音声 (0001.wav など)、概要、デバッグの詳細を含んだ ZIP ファイルに格納されます。各ファイル名の番号付きプレフィックス (以下の例では [nnnn]) は、バッチ合成を作成する際に使用したテキスト入力と同じ順序になります。

Note

[nnnn].debug.json ファイルには、合成結果の ID など、トラブルシューティングに役立つ可能性のある情報が格納されています。格納されるプロパティは変化する可能性があるので、どのような形であれ、この JSON 形式に依存することは避けてください。

各テキスト入力の合成結果は summary ファイルに格納されます。 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 Created

HTTP 201 Created は、(HTTP PUT での) バッチ合成作成要求が成功したことを示します。

HTTP 204 エラー

HTTP 204 エラーは、要求は成功したが、リソースが存在しないことを示します。次に例を示します。

存在しない合成ジョブを取得または削除しようとしました。
合成ジョブが正常に削除されました。

HTTP 400 エラー

400 エラーが発生する可能性のある例を次に示します。

outputFormat がサポートされていないか無効である。有効なフォーマット値を指定してください。既定の設定を使用する場合は outputFormat を空のままにします。
要求されたテキスト入力の数が上限である 10,000 件を超えた。
無効なデプロイ ID または正常にデプロイされていないカスタム音声を使用しようとした。 Speech リソースがカスタム音声にアクセスできること、また、カスタム音声が正常にデプロイされていることを確認してください。また、バッチ合成要求における {"your-custom-voice-name": "your-deployment-ID"} のマッピングが正しいことを確認する必要があります。
F0 Speech リソースを使おうとしたが、リージョンでサポートされている Speech リソースの価格レベルが Standard のみである。

HTTP 404 エラー

指定されたエンティティが見つかりません。合成 ID が正しいことを確認してください。

HTTP 429 エラー

直近の要求が多すぎます。各クライアントアプリケーションが各 Speech リソースに対して送信できる要求は 10 秒につき 100 個までです。 1 秒あたりの要求の数を減らしてください。

HTTP 500 エラー

HTTP 500 内部サーバーエラーは、要求が失敗したことを示します。エラーメッセージは応答本文に含まれています。

HTTP エラーの例

ここに示したのは、ジョブの作成には inputs プロパティが必要であるために HTTP 400 エラーになる要求の例です。

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 Created

HTTP 204 エラー

HTTP 400 エラー

HTTP 404 エラー

HTTP 429 エラー

HTTP 500 エラー

HTTP エラーの例

次のステップ

フィードバック

その他のリソース

次の方法で共有

テキスト読み上げ用のバッチ合成 API

バッチ合成を作成する

バッチ合成を取得する

バッチ合成を一覧表示する

バッチ合成を削除する

バッチ合成の結果

バッチ合成の待機時間とベスト プラクティス

バッチ合成の待機時間

ベスト プラクティス

HTTP 状態コード

HTTP 200 OK

HTTP 201 Created

HTTP 204 エラー

HTTP 400 エラー

HTTP 404 エラー

HTTP 429 エラー

HTTP 500 エラー

HTTP エラーの例

次のステップ

フィードバック

その他のリソース

バッチ合成の待機時間とベストプラクティス

ベストプラクティス