HTTP インターフェース

テキストからの音声の合成

テキストを音声に合成するには、サービスの /v1/synthesize メソッドの 2 つのバージョンのいずれかを呼び出します。

• GET /v1/synthesize メソッドは、必須の text 照会パラメーターで合成用のテキストを受け取ります。 要求の最大サイズは 8 KB で、これには入力テキスト、指定する SSML、URL、ヘッダーが含まれます。
• POST /v1/synthesize メソッドは、必須の要求本体に含まれた JSON 構造体として合成用のテキストを受け取ります。 要求の最大サイズは、URL とヘッダーが 8 KB、要求本体で送信する入力テキストが 5 KB です。 この 5 KB 制限には、指定する SSML も含まれます。

/v1/synthesize メソッドの 2 つのバージョンには、以下の共通のパラメーターがあります。

accept (照会パラメーター、任意指定ストリング)

サービスから返される音声として要求する音声フォーマット (MIME タイプ) を指定します。 この値は、HTTP の Accept 要求ヘッダーで指定することもできます。 accept 照会パラメーターの引数を URL エンコードします。 デフォルトでは、サービスは audio/ogg;codecs=opus のフォーマットで音声を返します。 詳しくは、音声フォーマットの使用を参照してください。

Oggオーディオ・フォーマットはサファリ・ブラウザではサポートされていません。 SafariブラウザでText to Speechサービスを使用している場合は、音声を返す別のフォーマットを指定する必要があります。

voice (照会パラメーター、任意指定ストリング)

テキストを音声で発話する際の声を指定します。 サポートされる音声の現在のリストを取得するには、/v1/voices メソッドを使用します。 デフォルトの音声を使用するには、このパラメーターを省略します。 詳しくは、「言語とボイス」および「デフォルトのボイスを使用する」を参照してください。

customization_id (照会パラメーター、任意指定ストリング)

合成に使用するカスタム・モデルの GUID (Globally Unique Identifier) を指定します。 指定したカスタム・モデルは、合成用に使用する音声の言語と一致する必要があります。 カスタマイズ ID を含める場合は、カスタム・モデルを所有するサービス・インスタンスの資格情報を使用して要求を発行する必要があります。 カスタマイズなしで指定音声を使用する場合は、このパラメーターを省略します。 詳しくは、カスタマイズの理解を参照してください。

rate_percentage (query parameter, 任意 integer)

合成リクエスト全体のグローバルスピーキングレートを指定します。 話す速度は、サービスが音声合成したテキストを話す速度である。 レートを高くすると、テキストはより速く話され、レートを低くすると、テキストはよりゆっくりと話される。 このパラメータは、リクエスト全体の音声ごとのデフォルトレートを変更する。 詳しくは、スピーキングレートの変更 をご覧ください。

pitch_percentage (query parameter, 任意 integer)

合成リクエスト全体のグローバルなスピーキングピッチを指定します。 スピーキングピッチは、サービスが合成する音声のトーンを表す。 声のトーンの高さや低さが聞き手にどの程度感じられるかを表す。 ピッチが高ければ高いトーンで話し、低ければ低いトーンで話すことになる。 このパラメータは、リクエスト全体のボイスごとのデフォルトピッチを変更します。 詳しくは、ピッチの変更 をご覧ください。

spell_out_mode (照会パラメーター、任意指定ストリング)

*ドイツ語音声の場合、*文字列の個々の文字をどのように綴るかを指定する。 デフォルトでは、このサービスは、その言語のテキストを合成するのと同じ速度で個々の文字を綴ります。 このパラメータを使用すると、個々の文字を1つ singles 2つ pairs または3つ triples のグループに分けて、よりゆっくりと綴るようサービスに指示することができる。詳細については、文字列のスペルアウト方法を指定する を参照してください。

X-Watson-Metadata (要求ヘッダー、任意指定 ストリング)

要求で渡されるデータに顧客 ID を関連付けます。 詳しくは、 機密保護を参照してください。

X-Watson-Learning-Opt-Out (要求ヘッダー、任意指定 ブール)

IBM Cloud 将来のユーザーのためにサービスを改善するために、サービスがリクエストおよびレスポンスのデータをログに記録するかどうかを示します。 一般的なサービス改善の目的で IBM がお客様のデータにアクセスすることを阻止するには、このパラメーターに対して true を指定します。 オプトアウトすると、要求に応じて IBM がディスクにいいえユーザー・データ (テキストまたは音声) を書き込むように指示されます。 アカウントレベルでオプトアウトすることもできます。 詳しくは、要求ロギングを参照してください。

/v1/synthesize メソッドの入力の一部として無効な照会パラメーターまたは JSON フィールドを指定すると、無効な引数のリストと説明が含まれる Warnings 応答ヘッダーがサービスから返されます。 警告に関係なく要求は成功します。

入力テキストの指定

POSTメソッドとGET /v1/synthesizeメソッドは両方とも、プレーン入力テキスト、または SSML でアノテーションが付けられたテキストを受け入れます。 2 つのバージョンは、主に、合成するテキストの指定方法が異なります。 以下の例は、両方ともプレーン・テキストのHello worldを渡します。

• POST /v1/synthesize メソッドは、要求本体に指定された入力テキストを受け取ります。 入力は、プレーン・テキストまたは SSML を含む単純な JSON 構成で指定します。 また、application/json ヘッダーに Content-Type という値を指定する必要もあります。

  IBM Cloud

  curl -X POST -u "apikey:{apikey}" \
  --header "Content-Type: application/json" \
  --header "Accept: audio/wav" \
  --output hello_world.wav \
  --data "{\"text\":\"Hello world\"}" \
  "{url}/v1/synthesize?voice=en-US_MichaelV3Voice"
  

  IBM Cloud Pak for Data IBM Software Hub

  curl -X POST \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --header "Accept: audio/wav" \
  --output hello_world.wav \
  --data "{\"text\":\"Hello world\"}" \
  "{url}/v1/synthesize?voice=en-US_MichaelV3Voice"
  

• GET /v1/synthesize メソッドは、text 照会パラメーターで指定された入力テキストを受け取ります。 入力はプレーン・テキストまたは SSML として指定します。どちらも URL エンコードする必要があります。

  IBM Cloud

  curl -X GET -u "apikey:{apikey}" \
  --header "Accept: audio/wav" \
  --output hello_world.wav \
  "{url}/v1/synthesize?text=Hello%20world&voice=en-US_MichaelV3Voice"
  

  IBM Cloud Pak for Data IBM Software Hub

  curl -X GET \
  --header "Authorization: Bearer {token}" \
  --header "Accept: audio/wav" \
  --output hello_world.wav \
  "{url}/v1/synthesize?text=Hello%20world&voice=en-US_MichaelV3Voice"""
  

POSTメソッドとGETメソッドは同等の機能を提供しますが、POSTメソッドを使用してサービスに入力テキストを渡す方が常に安全です。 POST要求は、要求の本体に入力を渡します。 GET要求は、URL 内のデータを公開します。

入力テキストに句読点を付ける

通常使用する句読点で合成するためのテキストを記述します。 例えば、通常の記述と同じように、コンマ、ピリオド、感嘆符、および疑問符を含めます。

サービスは、テキストの合成時に句読点を考慮します。 例えば、コンマと文の終わりの句読点は、合成音声の適切な場所に一時停止を挿入することによって音声に影響します。 ピリオド、感嘆符、疑問符などの文の終わりの句読点も、スピーチのイントネーションと屈折を変更します。 また、SSML 要素を使用して、音声のこれらの側面に影響を与えることもできます。

SSML 入力の指定

SSML (Speech Synthesis Markup Language) は、Text to Speech サービスなどの音声合成アプリケーションでテキストのアノテーションを利用するために設計された XML ベースのマークアップ言語です。 SSML 要素およびその属性を使用して、合成および結果の音声出力をより詳細に制御できます。

SSML を使用して入力テキストにアノテーションを付ける方法について詳しくは、SSML についてを参照してください。 サポートされるすべてのエレメントおよび属性のインベントリーについては、SSML 要素を参照してください。

XML 制御文字のエスケープ

ユーザーは XML ベースの SSML アノテーションを含む入力テキストを送信できるため、サービスではすべての入力を検証し、SSMLが正確で適切な形式になっていることを確認します。 したがって、入力に SSML が含まれているかどうかに関係なく、入力テキスト内に存在するすべての XML 制御文字をエスケープする必要があります。 表 1 に記している文字は、対応するエスケープ・ストリングまたは文字エンコードに置き換えてください。

サービスによる入力テキストの検証について詳しくは、SSML 検証を参照してください。

入力テキストの例

HTTP インターフェースの両方のメソッドについて、入力テキストの指定方法を示す例を以下に記載します。 XML 制御文字のエスケープの方法も例から確認できます。 例では、読みやすさのために改行を入れています。 実際の入力には改行を入れない でください。

"What have I learned?" he asked. "Everything!"