Text to Speech REST API

Speech Service では、REST API を使用して、テキストを合成音声に変換したり、リージョンでサポートされている音声の一覧を取得したりできます。 この記事では、認可オプション、クエリ オプション、要求の構築方法、および応答の解釈方法について説明します。

Text to Speech REST API では、多くのロケールでニューラル テキスト読み上げ音声がサポートされています。 利用可能な各エンドポイントは、リージョンに関連付けられています。 使用する予定のエンドポイントまたはリージョンの API キーが必要です。 詳細情報へのリンクを以下に示します。

• 音声の完全なリストについては、「音声サービスの言語と音声のサポート」を参照してください。
• リージョンの利用可能性については、「音声サービスがサポートされているリージョン」を参照してください。
• 21Vianet のエンドポイントによって運営される Azure Government と Microsoft Azure については、ソブリン クラウドに関するこちらの記事を参照してください。

Text to speech REST API を使用する前に、サービスにアクセスするための認証の一部としてトークン交換を完了する必要があることを覚えておいてください。 詳細については、認証に関するページをご覧ください。

音声の一覧を取得する

tts.speech.microsoft.com/cognitiveservices/voices/list エンドポイントを使用して、特定のリージョンまたはエンドポイントの音声の完全なリストを取得できます。 音声の一覧エンドポイントにリージョンのプレフィックスを付けて、そのリージョンの音声の一覧を取得します。 たとえば、westus リージョンの音声の一覧を取得するには、https://westus.tts.speech.microsoft.com/cognitiveservices/voices/list エンドポイントを使用します。 サポートされているすべてのリージョンの一覧については、リージョンのドキュメントを参照してください。

要求ヘッダー

この表は、テキスト読み上げ要求の必須のヘッダーと省略可能なヘッダーの一覧です。

要求本文

このエンドポイントへの GET 要求の本文は不要です。

要求のサンプル

この要求には Authorization ヘッダーのみが必要です。

GET /cognitiveservices/voices/list HTTP/1.1

Host: westus.tts.speech.microsoft.com
Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY

curl コマンドの例を次に示します。

curl --___location --request GET 'https://YOUR_RESOURCE_REGION.tts.speech.microsoft.com/cognitiveservices/voices/list' \
--header 'Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY'

応答のサンプル

サポートされているすべてのロケール、音声、性別、スタイル、その他の詳細を含む応答を JSON 本文で受け取る必要があります。 各音声の WordsPerMinute プロパティを使用して、出力音声の長さを推定できます。 次の JSON の例は、応答の構造を示すために部分的な結果を示しています。

[
    // Redacted for brevity
    {
        "Name": "Microsoft Server Speech Text to Speech Voice (en-US, JennyNeural)",
        "DisplayName": "Jenny",
        "LocalName": "Jenny",
        "ShortName": "en-US-JennyNeural",
        "Gender": "Female",
        "Locale": "en-US",
        "LocaleName": "English (United States)",
        "StyleList": [
          "assistant",
          "chat",
          "customerservice",
          "newscast",
          "angry",
          "cheerful",
          "sad",
          "excited",
          "friendly",
          "terrified",
          "shouting",
          "unfriendly",
          "whispering",
          "hopeful"
        ],
        "SampleRateHertz": "24000",
        "VoiceType": "Neural",
        "Status": "GA",
        "ExtendedPropertyMap": {
          "IsHighQuality48K": "True"
        },
        "WordsPerMinute": "152"
    },
    // Redacted for brevity
    {
        "Name": "Microsoft Server Speech Text to Speech Voice (en-US, JennyMultilingualNeural)",
        "DisplayName": "Jenny Multilingual",
        "LocalName": "Jenny Multilingual",
        "ShortName": "en-US-JennyMultilingualNeural",
        "Gender": "Female",
        "Locale": "en-US",
        "LocaleName": "English (United States)",
        "SecondaryLocaleList": [
          "de-DE",
          "en-AU",
          "en-CA",
          "en-GB",
          "es-ES",
          "es-MX",
          "fr-CA",
          "fr-FR",
          "it-IT",
          "ja-JP",
          "ko-KR",
          "pt-BR",
          "zh-CN"
        ],
        "SampleRateHertz": "24000",
        "VoiceType": "Neural",
        "Status": "GA",
        "WordsPerMinute": "190"
    },
    // Redacted for brevity
    {
        "Name": "Microsoft Server Speech Text to Speech Voice (ga-IE, OrlaNeural)",
        "DisplayName": "Orla",
        "LocalName": "Orla",
        "ShortName": "ga-IE-OrlaNeural",
        "Gender": "Female",
        "Locale": "ga-IE",
        "LocaleName": "Irish (Ireland)",
        "SampleRateHertz": "24000",
        "VoiceType": "Neural",
        "Status": "GA",
        "WordsPerMinute": "139"
    },
    // Redacted for brevity
    {
        "Name": "Microsoft Server Speech Text to Speech Voice (zh-CN, YunxiNeural)",
        "DisplayName": "Yunxi",
        "LocalName": "云希",
        "ShortName": "zh-CN-YunxiNeural",
        "Gender": "Male",
        "Locale": "zh-CN",
        "LocaleName": "Chinese (Mandarin, Simplified)",
        "StyleList": [
          "narration-relaxed",
          "embarrassed",
          "fearful",
          "cheerful",
          "disgruntled",
          "serious",
          "angry",
          "sad",
          "depressed",
          "chat",
          "assistant",
          "newscast"
        ],
        "SampleRateHertz": "24000",
        "VoiceType": "Neural",
        "Status": "GA",
        "RolePlayList": [
          "Narrator",
          "YoungAdultMale",
          "Boy"
        ],
        "WordsPerMinute": "293"
    },
    // Redacted for brevity
]

HTTP 状態コード

各応答の HTTP 状態コードは、成功または一般的なエラーを示します。

テキストを音声に変換する

cognitiveservices/v1 エンドポイントでは、音声合成マークアップ言語 (SSML) を使用してテキストを音声に変換することができます。

リージョンとエンドポイント

REST API を介したテキスト読み上げは、以下のリージョンでサポートされます。 必ず、ご利用の Speech リソースのリージョンと一致するエンドポイントを選択してください。

標準音声

この表を使用して、リージョンまたはエンドポイントごとのニューラル音声の利用可能性を判断します。

カスタム音声

カスタム音声を作成した場合は、作成したエンドポイントを使用します。 次のエンドポイントを使用することもできます。 {deploymentId}をカスタム音声モデルのデプロイ ID に置き換えます。

Long Audio API

Long Audio API は、一意のエンドポイントを持つ複数のリージョンで使用できます。

要求ヘッダー

この表は、テキスト読み上げ要求の必須のヘッダーと省略可能なヘッダーの一覧です。

要求本文

カスタム音声を使用している場合は、要求の本文をプレーン テキスト (ASCII または UTF-8) として送信できます。 それ以外の場合は、各 POST 要求の本文が SSML として送信されます。 SSML では、テキスト読み上げ機能が返す合成音声の音声と言語を選ぶことができます。 サポートされている音声の完全なリストについては、「音声サービスの言語と音声のサポート」を参照してください。

要求のサンプル

この HTTP 要求は、SSML を使用して音声と言語を指定します。 本文が長すぎて、生成されるオーディオが 10 分を超える場合は、10 分に切り捨てられます。 つまり、オーディオの長さが 10 分を超えることはできません。

POST /cognitiveservices/v1 HTTP/1.1

X-Microsoft-OutputFormat: riff-24khz-16bit-mono-pcm
Content-Type: application/ssml+xml
Host: westus.tts.speech.microsoft.com
Content-Length: <Length>
Authorization: Bearer [Base64 access_token]
User-Agent: <Your application name>

<speak version='1.0' xml:lang='en-US'><voice xml:lang='en-US' xml:gender='Male'
    name='en-US-ChristopherNeural'>
        I'm excited to try text to speech!
</voice></speak>

^* Content-Length には、独自のコンテンツ長を使用する必要があります。 ほとんどの場合、この値は自動的に計算されます。

HTTP 状態コード

各応答の HTTP 状態コードは、成功または一般的なエラーを示します。

HTTP ステータスが 200 OK の場合、応答の本文には要求された形式のオーディオ ファイルが含まれています。 このファイルは、転送と同時に再生することも、バッファーまたはファイルに保存することもできます。

オーディオ出力

サポートされているストリーミングおよび非ストリーミング オーディオ形式は、各要求で X-Microsoft-OutputFormat ヘッダーとして送信されます。 各形式には、ビット レートとエンコードの種類が組み込まれています。 音声サービスでは、48 kHz、24 kHz、16 kHz、および 8 kHz のオーディオ出力がサポートされます。 各標準音声モデルは、24kHz および高忠実度 48 kHz で利用できます。

amr-wb-16000hz
audio-16khz-16bit-32kbps-mono-opus
audio-16khz-32kbitrate-mono-mp3
audio-16khz-64kbitrate-mono-mp3
audio-16khz-128kbitrate-mono-mp3
audio-24khz-16bit-24kbps-mono-opus
audio-24khz-16bit-48kbps-mono-opus
audio-24khz-48kbitrate-mono-mp3
audio-24khz-96kbitrate-mono-mp3
audio-24khz-160kbitrate-mono-mp3
audio-48khz-96kbitrate-mono-mp3
audio-48khz-192kbitrate-mono-mp3
g722-16khz-64kbps
ogg-16khz-16bit-mono-opus
ogg-24khz-16bit-mono-opus
ogg-48khz-16bit-mono-opus
raw-8khz-8bit-mono-alaw
raw-8khz-8bit-mono-mulaw
raw-8khz-16bit-mono-pcm
raw-16khz-16bit-mono-pcm
raw-16khz-16bit-mono-truesilk
raw-22050hz-16bit-mono-pcm
raw-24khz-16bit-mono-pcm
raw-24khz-16bit-mono-truesilk
raw-44100hz-16bit-mono-pcm
raw-48khz-16bit-mono-pcm
webm-16khz-16bit-mono-opus
webm-24khz-16bit-24kbps-mono-opus
webm-24khz-16bit-mono-opus

riff-8khz-8bit-mono-alaw
riff-8khz-8bit-mono-mulaw
riff-8khz-16bit-mono-pcm
riff-22050hz-16bit-mono-pcm
riff-24khz-16bit-mono-pcm
riff-44100hz-16bit-mono-pcm
riff-48khz-16bit-mono-pcm

認証

各要求には Authorization ヘッダーが必要です。 次の表は、各機能でサポートされているヘッダーを示したものです。

Ocp-Apim-Subscription-Key ヘッダーを使用する場合は、リソース キーのみを指定する必要があります。 次に例を示します。

'Ocp-Apim-Subscription-Key': 'YourSpeechResourceKey'

Authorization: Bearer ヘッダーを使用する場合は、issueToken エンドポイントに対して要求を実行する必要があります。 この要求では、リソース キーを、10 分間有効なアクセス トークンと交換します。

もう 1 つのオプションは、Authorization: Bearer ヘッダーも使用するが、Microsoft Entra ID を介して発行されたトークンを使用する Microsoft Entra 認証を使用することです。 「Microsoft Entra 認証を使用する」を参照してください。

アクセス トークンを取得する方法

アクセス トークンを取得するには、issueToken とリソース キーを使用して、Ocp-Apim-Subscription-Key エンドポイントに対して要求を実行する必要があります。

issueToken エンドポイントの形式は次のとおりです。

https://<REGION_IDENTIFIER>.api.cognitive.microsoft.com/sts/v1.0/issueToken

<REGION_IDENTIFIER> は、お使いの Azure Cognitive Service for Speech リソースのリージョンと一致する識別子に置き換えてください。

アクセス トークン要求の作成にあたっては、以下のサンプルを使用してください。

HTTP のサンプル

この例は、トークンを取得するための単純な HTTP 要求です。 YourSpeechResourceKey は、お使いの Azure Cognitive Service for Speech サービスのリソース キーに置き換えてください。 Speech リソースが米国西部リージョンにない場合は、 Host ヘッダーをリージョンのホスト名に置き換えます。

POST /sts/v1.0/issueToken HTTP/1.1
Ocp-Apim-Subscription-Key: YourSpeechResourceKey
Host: eastus.api.cognitive.microsoft.com
Content-type: application/x-www-form-urlencoded
Content-Length: 0

応答の本文には、JSON Web トークン (JWT) 形式のアクセス トークンが格納されます。

PowerShell のサンプル

この例は、アクセス トークンを取得するための単純な PowerShell スクリプトです。 YourSpeechResourceKey は、お使いの Azure Cognitive Service for Speech サービスのリソース キーに置き換えてください。 必ず、Speech リソースに一致するリージョンに適切なエンドポイントを使用してください。 この例では現在、米国西部に設定されています。

$FetchTokenHeader = @{
  'Content-type'='application/x-www-form-urlencoded';
  'Content-Length'= '0';
  'Ocp-Apim-Subscription-Key' = 'YourSpeechResourceKey'
}

$OAuthToken = Invoke-RestMethod -Method POST -Uri https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken
 -Headers $FetchTokenHeader

# show the token received
$OAuthToken

cURL のサンプル

cURL は Linux (および Windows Subsystem for Linux) で使用できるコマンドライン ツールです。 この cURL コマンドは、アクセス トークンを取得する方法を示しています。 YourSpeechResourceKey は、お使いの Azure Cognitive Service for Speech サービスのリソース キーに置き換えてください。 必ず、Speech リソースに一致するリージョンに適切なエンドポイントを使用してください。 この例では現在、米国西部に設定されています。

curl -v -X POST \
 "https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken" \
 -H "Content-type: application/x-www-form-urlencoded" \
 -H "Content-Length: 0" \
 -H "Ocp-Apim-Subscription-Key: YourSpeechResourceKey"

C# のサンプル

この C# クラスは、アクセス トークンを取得する方法を示しています。 クラスをインスタンス化するときに、お使いの Azure Cognitive Service for Speech サービスのリソース キーを渡す必要があります。 Speech リソースが米国西部リージョンにない場合は、Speech リソースのリージョンと一致するように FetchTokenUri の値を変更します。

public class Authentication
{
    public static readonly string FetchTokenUri =
        "https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken";
    private string subscriptionKey;
    private string token;

    public Authentication(string subscriptionKey)
    {
        this.subscriptionKey = subscriptionKey;
        this.token = FetchTokenAsync(FetchTokenUri, subscriptionKey).Result;
    }

    public string GetAccessToken()
    {
        return this.token;
    }

    private async Task<string> FetchTokenAsync(string fetchUri, string subscriptionKey)
    {
        using (var client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", subscriptionKey);
            UriBuilder uriBuilder = new UriBuilder(fetchUri);

            var result = await client.PostAsync(uriBuilder.Uri.AbsoluteUri, null);
            Console.WriteLine("Token Uri: {0}", uriBuilder.Uri.AbsoluteUri);
            return await result.Content.ReadAsStringAsync();
        }
    }
}

Python のサンプル

# Request module must be installed.
# Run pip install requests if necessary.
import requests

subscription_key = 'REPLACE_WITH_YOUR_KEY'


def get_token(subscription_key):
    fetch_token_url = 'https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken'
    headers = {
        'Ocp-Apim-Subscription-Key': subscription_key
    }
    response = requests.post(fetch_token_url, headers=headers)
    access_token = str(response.text)
    print(access_token)

アクセス トークンを使用する方法

このサービスには、アクセス トークンを Authorization: Bearer <TOKEN> ヘッダーとして送信する必要があります。 各アクセス トークンは 10 分間有効です。 新しいトークンはいつでも取得できますが、ネットワークのトラフィックと待機時間を最小限に抑えるために、同じトークンを 9 分間使用することをお勧めします。

次の例では、Speech to text REST API for short audio への HTTP 要求を示します。

POST /cognitiveservices/v1 HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN
Host: westus.stt.speech.microsoft.com
Content-type: application/ssml+xml
Content-Length: 199
Connection: Keep-Alive

// Message body here...

Microsoft Entra 認証を使用する

Speech to text REST API for short audio で Microsoft Entra 認証を使用するには、アクセス トークンを作成する必要があります。 リソース ID と Microsoft Entra アクセス トークンで構成されるアクセス トークンを取得する手順は、Speech SDK を使用する場合と同じです。 「Microsoft Entra 認証を使用する」の手順に従ってください

リソース ID と Microsoft Entra アクセス トークンを取得した後、次の形式に従って実際のアクセス トークンを構築できます。

aad#YOUR_RESOURCE_ID#YOUR_MICROSOFT_ENTRA_ACCESS_TOKEN

リソース ID とアクセス トークンの間に "aad#" プレフィックスと "#" (ハッシュ) 区切り記号を含める必要があります。

次の例では、Speech to text REST API for short audio への HTTP 要求を示します。

POST /cognitiveservices/v1 HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN
Host: westus.stt.speech.microsoft.com
Content-type: application/ssml+xml
Content-Length: 199
Connection: Keep-Alive

// Message body here...

トークンの有効期間など、Microsoft Entra アクセス トークンの詳細については、「Microsoft ID プラットフォームのアクセス トークン」を参照してください。

次のステップ

• 無料の Azure アカウントを作成してください
• カスタム音声の使用を開始する
• バッチ合成