テキスト読み上げアバターにバッチ合成を使用する方法

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

テキスト読み上げアバター用のバッチ合成 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 が含まれ明日。

次の方法で共有

テキスト読み上げアバターにバッチ合成を使用する方法

バッチ合成要求を作成する

バッチ合成を取得する

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

バッチ合成の結果ファイルを取得する

バッチ合成を削除する

次のステップ

フィードバック

その他のリソース