テキスト読み上げアバターにバッチ合成を使用する方法 (プレビュー)
Note
現在のところ、テキスト読み上げアバターはパブリック プレビュー段階にあります。 このプレビュー版はサービス レベル アグリーメントなしで提供されています。運用環境のワークロードに使用することはお勧めできません。 特定の機能はサポート対象ではなく、機能が制限されることがあります。 詳しくは、Microsoft Azure プレビューの追加使用条件に関するページをご覧ください。
テキスト読み上げアバター (プレビュー) 用のバッチ合成 API を使用すると、テキストをビデオ ファイルとして話すアバターに非同期で合成できます。 パブリッシャーとビデオ コンテンツ プラットフォームでは、この API を使用して、アバター ビデオ コンテンツをバッチで作成できます。 このアプローチは、トレーニング資料、プレゼンテーション、広告など、さまざまなユース ケースに適しています。
合成アバター ビデオは、システムがテキスト入力を受信した後に非同期的に生成されます。 生成されたビデオ出力は、バッチ モード合成でダウンロードできます。 合成用のテキストを送信し、合成状態をポーリングし、状態が成功を示す場合はビデオ出力をダウンロードします。 テキスト入力形式は、プレーン テキストまたは SSML (音声合成マークアップ言語) テキストである必要があります。
次の図は、ワークフローの概要を示しています。
バッチ合成を行うには、次の REST API 操作が使用できます。
操作 | Method | REST API の呼び出し |
---|---|---|
バッチ合成の作成 | PUT | avatar/batchsyntheses/{SynthesisId}?api-version=2024-04-15-preview |
バッチ合成の取得 | GET | avatar/batchsyntheses/{SynthesisId}?api-version=2024-04-15-preview |
バッチ合成の一覧表示 | GET | avatar/batchsyntheses/?api-version=2024-04-15-preview |
バッチ合成の削除 | DELETE | avatar/batchsyntheses/{SynthesisId}?api-version=2024-04-15-preview |
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-04-15-preview"
次の形式で応答本文を受け取る必要があります。
{
"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-04-15-preview" -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-04-15-preview" -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-04-15-preview&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-04-15-preview" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"
削除要求が成功した場合、応答ヘッダーには HTTP/1.1 204 No Content
が含まれ明日。