テキスト読み上げのバッチ合成プロパティ

重要

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

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

新しいバッチ合成ジョブを作成するときは、JSON 形式の一部のプロパティが必要です。 他のプロパティは省略可能です。 バッチ合成応答には、合成の状態と結果に関する情報を提供する他のプロパティが含まれています。 たとえば、outputs.result プロパティには、音声出力とログを含むバッチ合成結果ファイルの場所が含まれています。

バッチ合成のプロパティ

次の表に、バッチ合成のプロパティを示します。

プロパティ	説明
createdDateTime	バッチ合成ジョブが作成された日時。 このプロパティは読み取り専用です。
customVoices	カスタム音声の名前とそのデプロイ ID のマッピング。 例: "customVoices": {"your-custom-voice-name": "502ac834-6537-4bc3-9fd6-140114daa66d"} 音声名は synthesisConfig.voice (inputKind が "PlainText" に設定されている場合)、または inputs の SSML テキスト内 (inputKind が "SSML" に設定されている場合) で使用できます。 カスタム音声を使用するためには、このプロパティが必須となります。 ここで定義されていないカスタム音声を使用しようとすると、サービスからエラーが返されます。
description	バッチ合成の説明。 このプロパティは省略可能です。
id	パス内で渡したバッチ合成のジョブ ID。 このプロパティはパス内で必須です。
inputs	合成するプレーン テキストまたは SSML。 inputKind が "PlainText" に設定されている場合、「"inputs": [{"text": "The rainbow has seven colors."}]」のようにプレーンテキストを指定します。 inputKind が "SSML" に設定されている場合、「"inputs": [{"text": "<speak version='\''1.0'\'' xml:lang='\''en-US'\''><voice xml:lang='\''en-US'\'' xml:gender='\''Female'\'' name='\''en-US-AvaMultilingualNeural'\''>The rainbow has seven colors.</voice></speak>"}]」のように、音声合成マークアップ言語 (SSML) でテキストを指定します。 複数の音声出力ファイルが必要な場合、追加できるテキスト オブジェクトは最大 1,000 個です。 たとえば、合成して 2 つの音声出力ファイルを得るためには、入力テキストを「"inputs": [{"text": "synthesize this to a file"},{"text": "synthesize this to another file"}]」のようにします。 ただし、properties.concatenateResult プロパティが true に設定されている場合、同期された各結果は同じ音声出力ファイルに書き込まれます。 テキスト入力は段落を分ける必要ありません。 最大 1,000 個のテキスト入力の中で、"\r\n" (改行) 文字列を使用して新しい段落を指定することができます。 たとえば、2 つの段落を含んだ入力テキストを合成して同じ音声出力ファイルを得るためには、「"inputs": [{"text": "synthesize this to a file\r\nsynthesize this to another paragraph in the same file"}]」のようにします。 段落の上限はありませんが、JSON ペイロードの最大サイズ (すべてのテキスト入力およびその他のプロパティを含む) は 2 メガバイトです。 新しいバッチ合成ジョブを作成する場合、このプロパティは必須です。 合成ジョブを取得する際の応答には、このプロパティは含まれません。
internalId	バッチ合成の内部ジョブ ID。 このプロパティは読み取り専用です。
lastActionDateTime	status プロパティの値が変更された直近の日時。 このプロパティは読み取り専用です。
outputs.result	音声出力とログを含むバッチ合成結果ファイルの場所。 このプロパティは読み取り専用です。
properties	オプションのバッチ合成の構成設定の定義済みセット。
properties.sizeInBytes	音声出力のサイズ (バイト単位)。 このプロパティは読み取り専用です。
properties.billingDetails	customNeuralCharacters と neuralCharacters (事前構築済み) の音声によって処理されて課金された単語の数。 このプロパティは読み取り専用です。
properties.concatenateResult	結果を連結するかどうかを決定します。 省略可能な bool 値 ("true" または "false") であり、既定では "false" になります。
properties.decompressOutputFiles	出力先コンテナーで合成結果ファイルを解凍するかどうかを決定します。 このプロパティは、destinationContainerUrl プロパティが設定されているときにのみ設定できます。 省略可能な bool 値 ("true" または "false") であり、既定では "false" になります。
properties.destinationContainerUrl	バッチ合成の結果は、書き込み可能な Azure コンテナーに格納できます。 コンテナーの URI を共有アクセス署名 (SAS) トークンと共に指定しなかった場合は、Microsoft が管理するコンテナーに結果が格納されます。 保存されているアクセス ポリシーを使用した SAS はサポートされていません。 合成ジョブが削除されると、結果データも削除されます。 合成ジョブを取得する際の応答には、このオプション プロパティは含まれません。
properties.destinationPath	バッチ合成結果の保存に使用できるプレフィックス パス。 プレフィックス パスを指定しない場合、既定のプレフィックス パスは YourSpeechResourceId/YourSynthesisId です。 このオプション プロパティは、destinationContainerUrl プロパティが設定されているときにのみ設定できます。
properties.durationInMilliseconds	オーディオ出力の時間 (ミリ秒数)。 このプロパティは読み取り専用です。
properties.failedAudioCount	音声出力に失敗したバッチ合成入力の数。 このプロパティは読み取り専用です。
properties.outputFormat	音声出力形式。 許容される値については、オーディオ出力形式に関するセクションを参照してください。 既定の出力形式は riff-24khz-16bit-mono-pcm です。
properties.sentenceBoundaryEnabled	文の境界データを生成するかどうかを決定します。 省略可能な bool 値 ("true" または "false") であり、既定では "false" になります。 文の境界データが要求された場合、対応する [nnnn].sentence.json ファイルが結果データの ZIP ファイルに追加されます。
properties.succeededAudioCount	音声出力に成功したバッチ合成入力の数。 このプロパティは読み取り専用です。
properties.timeToLiveInHours	合成ジョブが作成されてから、合成の結果が自動的に削除されるまでの期間 (時間数)。 省略可能な設定であり、既定では 744 (31 日) になります。 最大 Time to Live は 31 日です。 "Succeeded" または "Failed" 状態の合成ジョブでは、自動削除の日時は lastActionDateTime + timeToLiveInHours プロパティと等しくなります。 それ以外の場合、合成の削除メソッドを呼び出せば、もっと早い段階でジョブを削除できます。
properties.wordBoundaryEnabled	単語の境界データを生成するかどうかを決定します。 省略可能な bool 値 ("true" または "false") であり、既定では "false" になります。 ワードの境界データが要求された場合、対応する [nnnn].word.json ファイルが結果データの ZIP ファイルに追加されます。
status	バッチ合成処理の状態。 状態は "NotStarted" から "Running" に、そして最後に "Succeeded" または "Failed" へと推移します。 このプロパティは読み取り専用です。
synthesisConfig	プレーンテキストのバッチ合成に使用する構成設定。 このプロパティは、inputKind が "PlainText" に設定されている場合にのみ適用されます。
synthesisConfig.backgroundAudio	各オーディオ出力のバックグラウンド オーディオ。 これは省略可能なプロパティであり、inputKind が "PlainText" に設定されている場合にのみ適用されます。
synthesisConfig.backgroundAudio.fadein	バックグラウンド オーディオのフェードインの時間 (ミリ秒単位)。 既定値は 0 で、"フェードインなし" に相当します。 指定可能な値: 0 から 10000 まで (始めと終わりを含める)。 詳細については、音声合成マークアップ言語 (SSML) のドキュメントの「バックグラウンド オーディオを追加する」にある属性の表を参照してください。 無効な値は無視されます。 これは省略可能なプロパティであり、inputKind が "PlainText" に設定されている場合にのみ適用されます。
synthesisConfig.backgroundAudio.fadeout	バックグラウンド オーディオのフェードアウトの時間 (ミリ秒単位)。 既定値は 0 であり、フェードアウトなしに相当します。指定可能な値: 0 から 10000 まで (始めと終わりを含める)。 詳細については、音声合成マークアップ言語 (SSML) のドキュメントの「バックグラウンド オーディオを追加する」にある属性の表を参照してください。 無効な値は無視されます。 これは省略可能なプロパティであり、inputKind が "PlainText" に設定されている場合にのみ適用されます。
synthesisConfig.backgroundAudio.src	バックグラウンド オーディオ ファイルの URI の場所。 詳細については、音声合成マークアップ言語 (SSML) のドキュメントの「バックグラウンド オーディオを追加する」にある属性の表を参照してください。 無効な値は無視されます。 このプロパティは、synthesisConfig.backgroundAudio が設定されている場合は必須です。
synthesisConfig.backgroundAudio.volume	バックグラウンド オーディオ ファイルの音量。 指定可能な値: 0 から 100 まで (始めと終わりを含める)。 既定値は 1 です。 詳細については、音声合成マークアップ言語 (SSML) のドキュメントの「バックグラウンド オーディオを追加する」にある属性の表を参照してください。 無効な値は無視されます。 これは省略可能なプロパティであり、inputKind が "PlainText" に設定されている場合にのみ適用されます。
synthesisConfig.pitch	音声出力のピッチ。 指定できる値については、音声合成マークアップ言語 (SSML) のドキュメントの「韻律を調整する」の表を参照してください。 無効な値は無視されます。 これは省略可能なプロパティであり、inputKind が "PlainText" に設定されている場合にのみ適用されます。
synthesisConfig.rate	音声出力のレート。 指定できる値については、音声合成マークアップ言語 (SSML) のドキュメントの「韻律を調整する」の表を参照してください。 無効な値は無視されます。 これは省略可能なプロパティであり、inputKind が "PlainText" に設定されている場合にのみ適用されます。
synthesisConfig.role	一部の音声では、読み上げロールプレイを調整できます。 音声は別の年齢と性別を模倣できますが、音声名は変更されません。 たとえば、女性の音声を模倣するために、男性の音声のピッチを上げ、イントネーションを変更することはできますが、音声名は変更されません。 役割が見つからないか、使用する音声でサポートされていない場合、この属性は無視されます。 音声ごとに使用できるスタイルについては、「音声のスタイルと役割」を参照してください。 これは省略可能なプロパティであり、inputKind が "PlainText" に設定されている場合にのみ適用されます。
synthesisConfig.speakerProfileId	パーソナル音声の話者プロファイル ID。 使用可能なパーソナル音声の基本モデル名については、パーソナル音声の統合に関する記事を参照してください。 話者プロファイル ID を取得する方法については、言語と音声のサポートに関する記事を参照してください。 このプロパティは、inputKind が "PlainText" に設定されている場合は必須です。
synthesisConfig.style	一部の音声では、話し方を調整して、陽気さ、共感、落ち着きなど、さまざまな感情を表現できます。 カスタマー サービス、ニュースキャスト、音声アシスタントなど、さまざまなシナリオで音声を最適化できます。 音声ごとに使用できるスタイルについては、「音声のスタイルと役割」を参照してください。 このオプション プロパティは、synthesisConfig.style が設定されている場合にのみ適用されます。
synthesisConfig.styleDegree	読み上げのスタイルの強度。 より強いスタイルやより柔らかいスタイルを指定して、音声の表現力を高めたり抑えたりできます。 指定できる値の範囲は 0.01 から 2 (0.01 と 2 を含む) です。 既定値は、定義済みのスタイル強度を表す 1 です。 最小単位は 0.01 で、ターゲットのスタイルにわずかに傾きます。 値を 2 にすると、既定のスタイル強度が 2 倍になります。 スタイルの強度が見つからないか、使用する音声でサポートされていない場合、この属性は無視されます。 音声ごとに使用できるスタイルについては、「音声のスタイルと役割」を参照してください。 これは省略可能なプロパティであり、inputKind が "PlainText" に設定されている場合にのみ適用されます。
synthesisConfig.voice	音声出力を読み上げる音声。 使用可能な事前構築済みニューラル音声については、言語と音声のサポートに関する記事を参照してください。 カスタム音声を使用するには、customVoices プロパティで有効なカスタム音声とデプロイ ID のマッピングを指定する必要があります。 パーソナル音声を使用するには、synthesisConfig.speakerProfileId プロパティを指定する必要があります。 このプロパティは、inputKind が "PlainText" に設定されている場合は必須です。
synthesisConfig.volume	音声出力のボリューム。 指定できる値については、音声合成マークアップ言語 (SSML) のドキュメントの「韻律を調整する」の表を参照してください。 無効な値は無視されます。 これは省略可能なプロパティであり、inputKind が "PlainText" に設定されている場合にのみ適用されます。
inputKind	inputs テキスト プロパティをプレーンテキストにするか SSML にするかを示します。 指定できる値は "PlainText" と "SSML" で、大文字と小文字は区別されません。 inputKind が "PlainText" に設定されている場合は、synthesisConfig 音声プロパティも設定する必要があります。 このプロパティは必須です。

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

音声を合成するためにバッチ合成を使用する場合、それにともなう待機時間を考慮し、最適な結果を得るためのベスト プラクティスを実践する必要があります。

バッチ合成の待機時間

バッチ合成の待機時間は、入力テキストの複雑さ、バッチに含まれる入力の数、基になるハードウェアの処理能力など、さまざまな要因によって異なります。

バッチ合成の待機時間 (おおよそ) は次のとおりです。

• 合成された音声出力の 50% の待機時間は 10 から 20 秒以内です。

• 合成された音声出力の 95% の待機時間は 120 秒以内です。

ベスト プラクティス

アプリケーションのバッチ合成を検討するとき、待機時間が要件を満たしているかどうか評価することをお勧めします。 待機時間が目的のパフォーマンスと一致する場合、バッチ合成が適切な選択肢となりえます。 ただし、待機時間がニーズを満たしていない場合は、リアルタイム API の使用を検討してください。

HTTP 状態コード

このセクションでは、バッチ合成 API の HTTP 応答コードとメッセージについて詳しく取り上げます。

HTTP 200 OK

HTTP 200 OK は、要求が成功したことを示します。

HTTP 201 Created

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

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."
  }
}

次のステップ

• 音声合成マークアップ言語 (SSML)
• テキスト読み上げのクイックスタート
• バッチ合成 API への移行