テキスト読み上げアバターにバッチ合成を使用する方法
テキスト読み上げアバター用のバッチ合成 API を使用すると、テキストを読み上げるアバターをビデオ ファイル形式で非同期的に合成できます。 パブリッシャーとビデオ コンテンツ プラットフォームでは、この API を使用して、アバター ビデオ コンテンツをバッチで作成できます。 このアプローチは、トレーニング資料、プレゼンテーション、広告など、さまざまなユース ケースに適しています。
合成アバター ビデオは、システムがテキスト入力を受信した後に非同期的に生成されます。 生成されたビデオ出力は、バッチ モード合成でダウンロードできます。 合成用のテキストを送信し、合成状態をポーリングし、状態が成功を示す場合はビデオ出力をダウンロードします。 テキスト入力形式は、プレーン テキストまたは SSML (音声合成マークアップ言語) テキストである必要があります。
次の図は、ワークフローの概要を示しています。
バッチ合成を行うには、次の REST API 操作が使用できます。
| 操作 | Method | REST API の呼び出し |
|---|---|---|
| バッチ合成の作成 | PUT | avatar/batchsyntheses/{SynthesisId}?api-version=2024-08-01 |
| バッチ合成の取得 | GET | avatar/batchsyntheses/{SynthesisId}?api-version=2024-08-01 |
| バッチ合成の一覧表示 | GET | avatar/batchsyntheses/?api-version=2024-08-01 |
| バッチ合成の削除 | DELETE | avatar/batchsyntheses/{SynthesisId}?api-version=2024-08-01 |
GitHub でコード サンプル参照できます。
バッチ合成要求を作成する
新しいバッチ合成ジョブを作成するときは、JSON 形式の一部のプロパティが必要です。 他のプロパティは省略可能です。 バッチ合成応答には、合成の状態と結果に関する情報を提供する他のプロパティが含まれています。 たとえば、outputs.result プロパティには、アバター ビデオが含まれているビデオ ファイルのダウンロード元の場所が含まれています。 outputs.summary から、概要とデバッグの詳細にアクセスできます。
バッチ合成要求を送信するには、次の手順に従って HTTP POST 要求本文を構築します:
- 必須の
inputKindプロパティを設定します。 inputKindプロパティがPlainTextに設定されている場合、synthesisConfigでvoiceプロパティも設定する必要があります。 次の例では、inputKindがSSMLに設定されているため、speechSynthesisは設定されていません。- 必須の
SynthesisIdプロパティを設定します。 同じ音声リソースに対して一意のSynthesisIdを選択します。SynthesisIdは 3 文字から 64 文字までの文字列になります。文字、数字、'-'、'_' を含めることができますが、文字または数字で始め、文字または数字で終わる必要があります。 - 必要な
talkingAvatarCharacterプロパティとtalkingAvatarStyleプロパティを設定します。 サポートされているアバターのキャラクターやスタイルについては、ここを参照してください。 - 必要に応じて、
videoFormatやbackgroundColorなどのプロパティを設定することもできます。 詳細については、「バッチ合成のプロパティ」を参照してください。
Note
許容される最大 JSON ペイロード サイズは 500 キロバイトです。
各音声リソースでは、最大 200 個のバッチ合成ジョブを同時に実行できます。
出力ビデオの最大長は現在 20 分であり、今後増加する可能性があります。
HTTP PUT 要求は、次の例に示すように URI を使用して行います。 YourSpeechKey を音声リソース キーに置き換え、YourSpeechRegion を音声リソース リージョンに置き換え、前述のように要求本文のプロパティをセットします。
curl -v -X PUT -H "Ocp-Apim-Subscription-Key: YourSpeechKey" -H "Content-Type: application/json" -d '{
"inputKind": "SSML",
"inputs": [
{
"content": "<speak version='\''1.0'\'' xml:lang='\''en-US'\''><voice name='\''en-US-AvaMultilingualNeural'\''>The rainbow has seven colors.</voice></speak>"
}
],
"avatarConfig": {
"talkingAvatarCharacter": "lisa",
"talkingAvatarStyle": "graceful-sitting"
}
}' "https://YourSpeechRegion.api.cognitive.microsoft.com/avatar/batchsyntheses/my-job-01?api-version=2024-08-01"
次の形式で応答本文を受け取る必要があります。
{
"id": "my-job-01",
"internalId": "5a25b929-1358-4e81-a036-33000e788c46",
"status": "NotStarted",
"createdDateTime": "2024-03-06T07:34:08.9487009Z",
"lastActionDateTime": "2024-03-06T07:34:08.9487012Z",
"inputKind": "SSML",
"customVoices": {},
"properties": {
"timeToLiveInHours": 744,
},
"avatarConfig": {
"talkingAvatarCharacter": "lisa",
"talkingAvatarStyle": "graceful-sitting",
"videoFormat": "Mp4",
"videoCodec": "hevc",
"subtitleType": "soft_embedded",
"bitrateKbps": 2000,
"customized": false
}
}
status プロパティは、NotStarted 状態から Running に、そして最後に Succeeded または Failed へと推移します。 Succeeded と Failed のどちらかの状態が返されるまで、バッチ合成取得 API を定期的に呼び出すことができます。
バッチ合成を取得する
バッチ合成ジョブの状態を取得するには、以下の例に示した URI を使用して HTTP GET 要求を行います。
YourSynthesisId をバッチ合成 ID に置き換え、YourSpeechKey を音声リソース キーに置き換えて、YourSpeechRegion を 音声リソース リージョンに置き換えます。
curl -v -X GET "https://YourSpeechRegion.api.cognitive.microsoft.com/avatar/batchsyntheses/YourSynthesisId?api-version=2024-08-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"
次の形式で応答本文を受け取る必要があります。
{
"id": "my-job-01",
"internalId": "5a25b929-1358-4e81-a036-33000e788c46",
"status": "Succeeded",
"createdDateTime": "2024-03-06T07:34:08.9487009Z",
"lastActionDateTime": "2024-03-06T07:34:12.5698769",
"inputKind": "SSML",
"customVoices": {},
"properties": {
"timeToLiveInHours": 744,
"sizeInBytes": 344460,
"durationInMilliseconds": 2520,
"succeededCount": 1,
"failedCount": 0,
"billingDetails": {
"neuralCharacters": 29,
"talkingAvatarDurationSeconds": 2
}
},
"avatarConfig": {
"talkingAvatarCharacter": "lisa",
"talkingAvatarStyle": "graceful-sitting",
"videoFormat": "Mp4",
"videoCodec": "hevc",
"subtitleType": "soft_embedded",
"bitrateKbps": 2000,
"customized": false
},
"outputs": {
"result": "https://stttssvcprodusw2.blob.core.windows.net/batchsynthesis-output/xxxxx/xxxxx/0001.mp4?SAS_Token",
"summary": "https://stttssvcprodusw2.blob.core.windows.net/batchsynthesis-output/xxxxx/xxxxx/summary.json?SAS_Token"
}
}
outputs.result フィールドから、アバター ビデオを含むビデオ ファイルをダウンロードできます。 outputs.summary フィールドを使用すると、概要とデバッグの詳細をダウンロードできます。 バッチ合成の結果の詳細については、「バッチ合成の結果」を参照してください。
バッチ合成を一覧表示する
音声リソースのすべてのバッチ合成ジョブを一覧表示するには、以下の例に示したように、URI を使用して HTTP GET 要求を行います。
YourSpeechKey を 音声リソースのキーに、YourSpeechRegion を音声リソースのリージョンに置き換えます。 URL には、必要に応じて、skip と top (ページ サイズ) のクエリ パラメーターを設定できます。 skip の既定値は 0 で、maxpagesize の既定値は 100 です。
curl -v -X GET "https://YourSpeechRegion.api.cognitive.microsoft.com/avatar/batchsyntheses?skip=0&maxpagesize=2&api-version=2024-08-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"
次の形式で応答本文を受け取る必要があります:
{
"value": [
{
"id": "my-job-02",
"internalId": "14c25fcf-3cb6-4f46-8810-ecad06d956df",
"status": "Succeeded",
"createdDateTime": "2024-03-06T07:52:23.9054709Z",
"lastActionDateTime": "2024-03-06T07:52:29.3416944",
"inputKind": "SSML",
"customVoices": {},
"properties": {
"timeToLiveInHours": 744,
"sizeInBytes": 502676,
"durationInMilliseconds": 2950,
"succeededCount": 1,
"failedCount": 0,
"billingDetails": {
"neuralCharacters": 32,
"talkingAvatarDurationSeconds": 2
}
},
"avatarConfig": {
"talkingAvatarCharacter": "lisa",
"talkingAvatarStyle": "casual-sitting",
"videoFormat": "Mp4",
"videoCodec": "h264",
"subtitleType": "soft_embedded",
"bitrateKbps": 2000,
"customized": false
},
"outputs": {
"result": "https://stttssvcprodusw2.blob.core.windows.net/batchsynthesis-output/xxxxx/xxxxx/0001.mp4?SAS_Token",
"summary": "https://stttssvcprodusw2.blob.core.windows.net/batchsynthesis-output/xxxxx/xxxxx/summary.json?SAS_Token"
}
},
{
"id": "my-job-01",
"internalId": "5a25b929-1358-4e81-a036-33000e788c46",
"status": "Succeeded",
"createdDateTime": "2024-03-06T07:34:08.9487009Z",
"lastActionDateTime": "2024-03-06T07:34:12.5698769",
"inputKind": "SSML",
"customVoices": {},
"properties": {
"timeToLiveInHours": 744,
"sizeInBytes": 344460,
"durationInMilliseconds": 2520,
"succeededCount": 1,
"failedCount": 0,
"billingDetails": {
"neuralCharacters": 29,
"talkingAvatarDurationSeconds": 2
}
},
"avatarConfig": {
"talkingAvatarCharacter": "lisa",
"talkingAvatarStyle": "graceful-sitting",
"videoFormat": "Mp4",
"videoCodec": "hevc",
"subtitleType": "soft_embedded",
"bitrateKbps": 2000,
"customized": false
},
"outputs": {
"result": "https://stttssvcprodusw2.blob.core.windows.net/batchsynthesis-output/xxxxx/xxxxx/0001.mp4?SAS_Token",
"summary": "https://stttssvcprodusw2.blob.core.windows.net/batchsynthesis-output/xxxxx/xxxxx/summary.json?SAS_Token"
}
}
],
"nextLink": "https://YourSpeechRegion.api.cognitive.microsoft.com/avatar/batchsyntheses/?api-version=2024-08-01&skip=2&maxpagesize=2"
}
outputs.result から、アバター ビデオを含むビデオ ファイルをダウンロードできます。 outputs.summary から、概要とデバッグの詳細にアクセスできます。 詳細については、「バッチ合成の結果」を参照してください。
合成要求は、JSON 応答の value プロパティにリストされます。 一覧は改ページ調整され、最大ページ サイズは 100 です。 ページ分割されたリストの後続ページを取得するための nextLink プロパティが必要に応じて提供されます。
バッチ合成の結果ファイルを取得する
status が "Succeeded" であるバッチ合成ジョブを取得したら、ビデオ出力の結果をダウンロードできます。 バッチ合成を取得したときに返される outputs.result プロパティから得られる URL を使用します。
バッチ合成の結果ファイルを取得するには、以下の例に示した URI を使用して HTTP GET 要求を行います。 YourOutputsResultUrl は、バッチ合成を取得したときに返される outputs.result プロパティから得られる URL に置き換えます。 YourSpeechKey をSpeech リソース キーに置き換えます。
curl -v -X GET "YourOutputsResultUrl" -H "Ocp-Apim-Subscription-Key: YourSpeechKey" > output.mp4
バッチ合成の概要ファイルを取得するには、以下の例に示した URI を使用して HTTP GET 要求を行います。 YourOutputsResultUrl は、バッチ合成を取得したときに返される outputs.summary プロパティから得られる URL に置き換えます。 YourSpeechKey をSpeech リソース キーに置き換えます。
curl -v -X GET "YourOutputsSummaryUrl" -H "Ocp-Apim-Subscription-Key: YourSpeechKey" > summary.json
各テキスト入力の合成結果は summary ファイルに格納されます。 summary.json ファイルの例を次に示します:
{
"jobID": "5a25b929-1358-4e81-a036-33000e788c46",
"status": "Succeeded",
"results": [
{
"texts": [
"<speak version='1.0' xml:lang='en-US'><voice name='en-US-AvaMultilingualNeural'>The rainbow has seven colors.</voice></speak>"
],
"status": "Succeeded",
"videoFileName": "244a87c294b94ddeb3dbaccee8ffa7eb/5a25b929-1358-4e81-a036-33000e788c46/0001.mp4",
"TalkingAvatarCharacter": "lisa",
"TalkingAvatarStyle": "graceful-sitting"
}
]
}
バッチ合成を削除する
オーディオ出力の結果を取得し、バッチ合成ジョブ履歴が不要になった後は、それを削除できます。 音声サービスによって各合成の履歴が保持される期間は、最大 31 日間または要求の timeToLiveInHours プロパティの期間のうちどちらか早い方となります。 "Succeeded" または "Failed" 状態の合成ジョブでは、自動削除の日時は lastActionDateTime プロパティおよび timeToLiveプロパティと等しくなります。
バッチ合成ジョブを削除するには、以下の例に示した URI を使用して HTTP DELETE 要求を行います。 YourSynthesisId をバッチ合成 ID に置き換え、YourSpeechKey を音声リソース キーに置き換えて、YourSpeechRegion を 音声リソース リージョンに置き換えます。
curl -v -X DELETE "https://YourSpeechRegion.api.cognitive.microsoft.com/avatar/batchsyntheses/YourSynthesisId?api-version=2024-08-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"
削除要求が成功した場合、応答ヘッダーには HTTP/1.1 204 No Content が含まれ明日。