Speech to text REST API for short audio
短い音声向けの音声テキスト変換 REST API のユース ケースは限られています。 Speech SDK を使用できない場合にのみ使用してください。
Speech to text REST API for short audio を使用する前に、次の制限事項を考慮してください。
- REST API for short audio を使用して音声を直接送信する要求には、最長 60 秒の音声を含めることができます。 入力のオーディオ形式は、Speech SDK に比べて多くの制限があります。
- REST API for short audio は最終的な結果のみを返します。 部分的な結果は提供されません。
- 音声翻訳 は、短いオーディオの REST API ではサポートされていません。 Speech SDK を使用する必要があります。
- 短いオーディオの REST API では、バッチ文字起こし と カスタム音声 はサポートされていません。 バッチ文字起こしとカスタム音声には 、常に Speech to Text REST API を使用する必要があります。
Speech to text REST API for short audio を使う前に、サービスにアクセスするための認証の一部としてトークン交換を完了する必要があることを覚えておいてください。 詳細については、認証に関するページをご覧ください。
リージョンとエンドポイント
REST API for short audio のエンドポイントの形式は次のとおりです。
https://<REGION_IDENTIFIER>.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1
<REGION_IDENTIFIER> は、お使いの Azure Cognitive Service for Speech リソースのリージョンと一致する識別子に置き換えてください。
Note
21Vianet のエンドポイントによって運営される Azure Government と Microsoft Azure については、ソブリン クラウドに関するこちらの記事を参照してください。
オーディオの形式
オーディオは HTTP POST 要求の本文で送信されます。 この表内のいずれかの形式にする必要があります。
| Format | コーデック | ビット レート | サンプル速度 |
|---|---|---|---|
| WAV | PCM 0 | 256 kbps | 16 kHz、モノラル |
| OGG | OPUS | 256 kbps | 16 kHz、モノラル |
Note
上の形式は、Speech サービスの REST API for short audio と WebSocket を介してサポートされます。 Speech SDK では PCM コーデックの WAV 形式と、その他の形式がサポートされています。
要求ヘッダー
次の表に、音声テキスト変換要求の必須ヘッダーと省略可能なヘッダーを示します。
| Header | 説明 | 必須または省略可能 |
|---|---|---|
Ocp-Apim-Subscription-Key |
Azure Cognitive Service for Speech サービスのリソース キー。 | このヘッダーと Authorization のどちらかが必須となります。 |
Authorization |
単語 Bearer が前に付いた認証トークン。 詳細については、認証に関するページをご覧ください。 |
このヘッダーと Ocp-Apim-Subscription-Key のどちらかが必須となります。 |
Pronunciation-Assessment |
認識結果に発音スコアを表示するためのパラメーターが指定されます。 これらのスコアは、音声入力の発音品質を、精度、流暢性、完全性のようなインジケーターで評価します。 このパラメーターは、複数の詳細パラメーターを含む、Base64 でエンコードされた JSON です。 このヘッダーの作成方法については、「発音評価パラメーター」を参照してください。 |
省略可能 |
Content-type |
指定したオーディオ データの形式とコーデックを記述します。 指定できる値は、audio/wav; codecs=audio/pcm; samplerate=16000 と audio/ogg; codecs=opus です。 |
必須 |
Transfer-Encoding |
オーディオを個別のファイルとしてではなくチャンク データとして送信することを指定します。 このヘッダーは、音声データをチャンクする場合にのみ使用します。 | オプション |
Expect |
チャンク転送を使用している場合、Expect: 100-continue を送信します。 Speech サービスは最初の要求を確認し、より多くのデータを待機します。 |
音声のチャンク データを送信する場合は必須となります。 |
Accept |
指定する場合は、application/json とする必要があります。 Speech Service からは、結果が JSON 形式で返されます。Speech Service からは、結果が JSON 形式で返されます。 一部の要求フレームワークでは、互換性のない既定値が提供されます。 常に Accept を含めることをお勧めします。 |
省略可能ですが、指定することをお勧めします。 |
クエリ パラメーター
REST 要求のクエリ文字列には、次のパラメーターを含めることができます。
注意
4xx HTTP エラーを受け取らないためには、URL に言語パラメーターを付加する必要があります。 たとえば、米国西部エンドポイントを使用する米国英語に設定される言語は https://westus.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?language=en-US です。
| パラメーター | 説明 | 必須または省略可能 |
|---|---|---|
language |
認識の対象として発話された言語を識別します。 サポートされている言語を参照してください。 | 必須 |
format |
結果の形式を指定します。 指定できる値は、simple と detailed です。 単純な結果には RecognitionStatus、DisplayText、Offset、Durationが含まれます。 詳細な応答には、表示テキストの 4 つの異なる表現が含まれます。 既定の設定は simple です。 |
省略可能 |
profanity |
認識結果内の不適切な表現をどう扱うかを指定します。 指定できる値は次のとおりです。masked。不適切表現をアスタリスクに置き換えます。 removed。結果からすべての不適切表現を削除します。 raw。結果にすべての不適切表現が含まれます。 既定の設定は masked です。 |
省略可能 |
cid |
Speech Studio を使用してカスタム モデルを作成する場合、[デプロイ] ページにある [エンドポイント ID] 値を使用できます。 cid クエリ文字列パラメーターの引数として [エンドポイント ID] の値を使用します。 |
省略可能 |
発音評価パラメーター
発音評価の必須パラメーターと省略可能なパラメーターを次の表に示します。
| パラメーター | 説明 | 必須または省略可能 |
|---|---|---|
ReferenceText |
発音が評価されるテキスト。 | 必須 |
GradingSystem |
スコア調整用のポイント システム。 FivePoint システムによって 0 から 5 の浮動小数点スコアが付与され、HundredMark によって 0 から 100 の浮動小数点スコアが付与されます。 既定値:FivePoint。 |
省略可能 |
Granularity |
評価の粒度。 指定できる値は次のとおりです。Phoneme。フルテキスト、単語、および音素レベルのスコアを示します。Word。フルテキストおよび単語レベルのスコアを示します。 FullText。フルテキスト レベルのみのスコアを示します。既定の設定は Phoneme です。 |
省略可能 |
Dimension |
出力条件を定義します。 指定できる値は次のとおりです。Basic。精度スコアのみを表示します。 Comprehensive。より多くの次元のスコアを表示します (フルテキスト レベルの流暢性スコアと完全性スコア、単語レベルのエラーの種類など)。さまざまなスコアの次元と単語エラーの種類の定義を確認するには、「応答プロパティ」をご覧ください。 既定の設定は Basic です。 |
省略可能 |
EnableMiscue |
誤りの計算を有効にします。 このパラメーターを有効にすると、発音された単語が参照テキストと比較されます。 これらは、比較に基づいて省略または挿入でマークされます。 指定できる値は、False と True です。 既定の設定は False です。 |
省略可能 |
ScenarioId |
カスタマイズされたポイント システムを示す GUID。 | オプション |
発音評価パラメーターを含む JSON の例を次に示します。
{
"ReferenceText": "Good morning.",
"GradingSystem": "HundredMark",
"Granularity": "FullText",
"Dimension": "Comprehensive"
}
次のサンプル コードは、発音評価パラメーターを Pronunciation-Assessment ヘッダーに組み込む方法を示しています。
var pronAssessmentParamsJson = $"{{\"ReferenceText\":\"Good morning.\",\"GradingSystem\":\"HundredMark\",\"Granularity\":\"FullText\",\"Dimension\":\"Comprehensive\"}}";
var pronAssessmentParamsBytes = Encoding.UTF8.GetBytes(pronAssessmentParamsJson);
var pronAssessmentHeader = Convert.ToBase64String(pronAssessmentParamsBytes);
音声データを投稿するときは、ストリーミング (チャンク転送) アップロードを行うことを強くお勧めします。これにより、待ち時間が大幅に短縮されます。 ストリーミングを有効にする方法については、さまざまなプログラミング言語のサンプル コードを参照してください。
注意
詳細については、「発音評価」を参照してください。
要求のサンプル
次のサンプルには、ホスト名と必要なヘッダーが含まれています。 サービスではオーディオ データも必要であり、このサンプルには含まれていないことに注意してください。 前述のようにチャンクにすることをお勧めしますが、必須ではありません。
POST speech/recognition/conversation/cognitiveservices/v1?language=en-US&format=detailed HTTP/1.1
Accept: application/json;text/xml
Content-Type: audio/wav; codecs=audio/pcm; samplerate=16000
Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY
Host: westus.stt.speech.microsoft.com
Transfer-Encoding: chunked
Expect: 100-continue
発音評価を有効にするには、次のヘッダーを追加します。 このヘッダーの作成方法については、「発音評価パラメーター」を参照してください。
Pronunciation-Assessment: eyJSZWZlcm...
HTTP 状態コード
各応答の HTTP 状態コードは、成功または一般的なエラーを示します。
| HTTP 状態コード | 説明 | 考えられる原因 |
|---|---|---|
| 100 | 続行 | 最初の要求が受け入れられます。 残りのデータの送信を続行します。 (このコードはチャンク転送で使用されます。) |
| 200 | OK | 要求は成功しました。 応答本文は JSON オブジェクトです。 |
| 400 | 正しくない要求 | 言語コードが指定されていないか、言語がサポートされていないか、音声ファイルが無効です (例)。 |
| 401 | 権限がありません | リソース キーまたは認証トークンが指定したリージョンで無効であるか、エンドポイントが無効です。 |
| 403 | Forbidden | リソース キーまたは認証トークンがありません。 |
応答のサンプル
simple 認識の一般的な応答を以下に示します。
{
"RecognitionStatus": "Success",
"DisplayText": "Remind me to buy 5 pencils.",
"Offset": "1236645672289",
"Duration": "1236645672289"
}
detailed 認識の一般的な応答を以下に示します。
{
"RecognitionStatus": "Success",
"Offset": "1236645672289",
"Duration": "1236645672289",
"NBest": [
{
"Confidence": 0.9052885,
"Display": "What's the weather like?",
"ITN": "what's the weather like",
"Lexical": "what's the weather like",
"MaskedITN": "what's the weather like"
},
{
"Confidence": 0.92459863,
"Display": "what is the weather like",
"ITN": "what is the weather like",
"Lexical": "what is the weather like",
"MaskedITN": "what is the weather like"
}
]
}
発音評価による認識に対する一般的な応答を以下に示します。
{
"RecognitionStatus": "Success",
"Offset": "400000",
"Duration": "11000000",
"NBest": [
{
"Confidence" : "0.87",
"Lexical" : "good morning",
"ITN" : "good morning",
"MaskedITN" : "good morning",
"Display" : "Good morning.",
"PronScore" : 84.4,
"AccuracyScore" : 100.0,
"FluencyScore" : 74.0,
"CompletenessScore" : 100.0,
"Words": [
{
"Word" : "Good",
"AccuracyScore" : 100.0,
"ErrorType" : "None",
"Offset" : 500000,
"Duration" : 2700000
},
{
"Word" : "morning",
"AccuracyScore" : 100.0,
"ErrorType" : "None",
"Offset" : 5300000,
"Duration" : 900000
}
]
}
]
}
応答プロパティ
結果は JSON 形式で返されます。 simple 形式には、次の最上位レベル フィールドが含まれます。
| プロパティ | 説明 |
|---|---|
RecognitionStatus |
認識成功を表す Success などのステータス。 次の表を参照してください。 |
DisplayText |
大文字/小文字、句読点、逆テキスト正規化、および不適切表現マスクの後に認識されたテキストです。 成功時にのみ存在します。 逆テキスト正規化は、"two hundred" の場合は 200、"Doctor smith" の場合は "Dr. Smith" など、音声テキストを短い形式に変換します。 |
Offset |
認識された音声がオーディオ ストリーム内で開始する時間 (100 ナノ秒単位)。 |
Duration |
認識された音声のオーディオ ストリーム内での持続時間 (100 ナノ秒単位)。 |
RecognitionStatus フィールドには、次の値が格納されます。
| 状態 | Description |
|---|---|
Success |
認識が成功し、DisplayText フィールドが存在する。 |
NoMatch |
音声ストリーム内に音声が検出されたが、ターゲット言語の単語は見つからなかった。 通常、この状態は、認識言語がユーザーが話している言語とは異なっていることを意味します。 |
InitialSilenceTimeout |
音声ストリームの先頭に無音状態しか含まれておらず、音声の待機中にサービスがタイムアウトした。 |
BabbleTimeout |
音声ストリームの先頭にノイズしか含まれておらず、音声の待機中にサービスがタイムアウトした。 |
Error |
認識サービスで内部エラーが発生し、続行できませんでした。 可能であれば再試行してください。 |
Note
オーディオが不適切な表現のみで構成されており、profanity クエリ パラメーターが remove に設定されている場合、サービスは音声結果を返しません。
この detailed 形式には、より多くの形式の認識された結果が含まれています。
detailed 形式を使用しているときは、NBest リストに含まれるそれぞれの結果について、DisplayText が Display として返されます。
NBest リスト内のオブジェクトには以下を含めることができます。
| プロパティ | Description |
|---|---|
Confidence |
0.0 (信頼度なし) から 1.0 (完全信頼) までのエントリの信頼度スコア。 |
Lexical |
認識されたテキストの語彙形式: 認識された実際の単語。 |
ITN |
認識されたテキストの逆テキスト正規化 (ITN) つまりカノニカル形式。電話番号、数字、略語 ("doctor smith" から "dr smith")、およびその他の変換を適用したものです。 |
MaskedITN |
要求された場合、不適切な表現のマスキングを適用した ITN 形式。 |
Display |
認識されたテキストの表示形式。句読点と大文字化を追加したものです。 このパラメーターは、形式を simple に設定したときに DisplayText から提供されるものと同じです。 |
AccuracyScore |
音声の発音精度。 精度は、音素がネイティブ スピーカーの発音とどれだけ厳密に一致しているかを示します。 単語およびフルテキスト レベルの精度スコアは、音素レベルの精度スコアから集計されます。 |
FluencyScore |
提供された音声の流暢性。 流暢性は、音声がネイティブ スピーカーによる単語間の間の取り方にどれだけ厳密に一致しているかを示します。 |
CompletenessScore |
音声の完全性。テキスト入力を参照するために発音された単語の比率を算出することで判断されます。 |
PronScore |
提供された音声の発音品質を示す全体的なスコア。 これは、重み付きの AccuracyScore、FluencyScore、および CompletenessScore から集計されます。 |
ErrorType |
ReferenceText と比較して、単語が省略されているか、挿入されているか、発音が正しくないかどうかを示す値。 指定できる値は、None (この単語にエラーがないことを意味します)、Omission、Insertion、および Mispronunciation です。 |
チャンク転送
チャンク転送 (Transfer-Encoding: chunked) は、認識の待ち時間を短縮するのに役立ちます。 これにより、Speech サービスが、音声ファイルを転送中に処理を開始できます。 短いオーディオ用の REST API では、部分的または中間的な結果は提供されません。
このコード サンプルは、音声をチャンクで送信する方法を示しています。 最初のチャンクだけに、オーディオ ファイルのヘッダーが含まれている必要があります。 request は、適切な REST エンドポイントに接続された HttpWebRequest オブジェクトです。 audioFile はディスク上のオーディオ ファイルのパスです。
var request = (HttpWebRequest)HttpWebRequest.Create(requestUri);
request.SendChunked = true;
request.Accept = @"application/json;text/xml";
request.Method = "POST";
request.ProtocolVersion = HttpVersion.Version11;
request.Host = host;
request.ContentType = @"audio/wav; codecs=audio/pcm; samplerate=16000";
request.Headers["Ocp-Apim-Subscription-Key"] = "YOUR_RESOURCE_KEY";
request.AllowWriteStreamBuffering = false;
using (var fs = new FileStream(audioFile, FileMode.Open, FileAccess.Read))
{
// Open a request stream and write 1,024-byte chunks in the stream one at a time.
byte[] buffer = null;
int bytesRead = 0;
using (var requestStream = request.GetRequestStream())
{
// Read 1,024 raw bytes from the input audio file.
buffer = new Byte[checked((uint)Math.Min(1024, (int)fs.Length))];
while ((bytesRead = fs.Read(buffer, 0, buffer.Length)) != 0)
{
requestStream.Write(buffer, 0, bytesRead);
}
requestStream.Flush();
}
}
認証
各要求には Authorization ヘッダーが必要です。 次の表は、各機能でサポートされているヘッダーを示したものです。
| サポートされている Authorization ヘッダー | 音声テキスト変換 | テキストを音声に変換する |
|---|---|---|
Ocp-Apim-Subscription-Key |
はい | イエス |
Authorization: Bearer |
イエス | はい |
Ocp-Apim-Subscription-Key ヘッダーを使用する場合、指定する必要があるのはリソース キーだけです。 次に例を示します。
'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
Authorization: Bearer ヘッダーを使用する場合は、issueToken エンドポイントに対して要求を実行する必要があります。 この要求では、リソース キーを、10 分間有効なアクセス トークンと交換します。
アクセス トークンを取得する方法
アクセス トークンを取得するには、Ocp-Apim-Subscription-Key とリソース キーを使用して、issueToken エンドポイントに対して要求を実行する必要があります。
issueToken エンドポイントの形式は次のとおりです。
https://<REGION_IDENTIFIER>.api.cognitive.microsoft.com/sts/v1.0/issueToken
ご利用のサブスクリプションのリージョンと一致する識別子で <REGION_IDENTIFIER> を置き換えてください。
アクセス トークン要求の作成にあたっては、以下のサンプルを使用してください。
HTTP のサンプル
この例は、トークンを取得するための単純な HTTP 要求です。 YOUR_SUBSCRIPTION_KEY は、お使いの Azure Cognitive Service for Speech サービスのリソース キーに置き換えてください。 お使いのサブスクリプションが米国西部リージョンにない場合は、Host ヘッダーをご自身のリージョンのホスト名に置き換えます。
POST /sts/v1.0/issueToken HTTP/1.1
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
Host: eastus.api.cognitive.microsoft.com
Content-type: application/x-www-form-urlencoded
Content-Length: 0
応答の本文には、JSON Web トークン (JWT) 形式のアクセス トークンが格納されます。
PowerShell のサンプル
この例は、アクセス トークンを取得するための単純な PowerShell スクリプトです。 YOUR_SUBSCRIPTION_KEY は、お使いの Azure Cognitive Service for Speech サービスのリソース キーに置き換えてください。 必ず、実際のサブスクリプションに合ったリージョンの正しいエンドポイントを使用してください。 この例では現在、米国西部に設定されています。
$FetchTokenHeader = @{
'Content-type'='application/x-www-form-urlencoded';
'Content-Length'= '0';
'Ocp-Apim-Subscription-Key' = 'YOUR_SUBSCRIPTION_KEY'
}
$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 コマンドは、アクセス トークンを取得する方法を示しています。 YOUR_SUBSCRIPTION_KEY は、お使いの Azure Cognitive Service for 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: YOUR_SUBSCRIPTION_KEY"
C# のサンプル
この C# クラスは、アクセス トークンを取得する方法を示しています。 クラスをインスタンス化するときに、お使いの Azure Cognitive Service for 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...