簡短音訊的語音轉換文字 REST API

簡短音訊的語音轉換文字 REST API 使用案例有限。 僅在您無法使用語音 SDK 的情況下再使用此功能。

使用語音轉換文字 REST API 進行簡短音訊之前，請考慮下列限制：

• 針對簡短音訊使用 REST API 並直接傳輸音訊的要求，最多可包含 60 秒的音訊。 相較於語音 SDK，輸入音訊格式比較有限。
• 簡短音訊的 REST API 僅會傳回最終結果。 此功能不提供部分結果。
• 針對簡短音訊，不支援透過 REST API 進行語音翻譯。 您必須使用 語音 SDK。
• 針對簡短音訊，不支援透過 REST API 處理批次轉譯和自訂語音。 您應該一律使用 語音轉換文字 REST API 進行批次轉譯和自訂語音。

使用語音轉換文字 REST API 進行簡短音訊之前，請先瞭解您需要在驗證過程中完成權杖交換，才能存取服務。 如需詳細資訊，請參閱驗證。

區域與端點

適用於簡短音訊的 REST API 端點具有如下格式：

https://<REGION_IDENTIFIER>.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1

使用與語音資源區域相符的識別碼來取代 <REGION_IDENTIFIER>。

注意

如需 Azure Government 和 Azure 中國端點相關資訊，請參閱關於主權雲端的文章。

自動格式

音訊是在 HTTP POST 要求的主體中傳送。 它必須是此表格中的格式之一：

格式	轉碼器	位元速率	採樣速率
WAV	PCM	256 kbps	16 kHz，單聲道
OGG	OPUS	256 kpbs	16 kHz，單聲道

注意

透過語音服務中適用於簡短音訊的 REST API 和 WebSocket 可支援前述格式。 語音 SDK 支援具備 PCM 轉碼器的 WAV 格式以及其他格式。

要求標頭

下表列出語音轉換文字要求的必要和選擇性標頭：

標頭	描述	必要或選用
Ocp-Apim-Subscription-Key	語音服務的資源金鑰。	必須有此標頭或 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。 語音服務會確認初始要求並等候其他資料。	如果您傳送的是區塊音訊資料，則為必要。
Accept	如果提供，則必須是 application/json。 語音服務提供 JSON 格式的結果。 某些要求架構會提供不相容的預設值。 最佳做法是一律包含 Accept。	此為選用步驟，但建議執行。

查詢參數

REST 要求的查詢字串中可能包括這些參數。

注意

您必須將語言參數附加到 URL 後方，以避免收到 4xx HTTP 錯誤。 例如，透過美國西部端點設定為美式英文的語言是：https://westus.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?language=en-US。

參數	描述	必要或選用
language	識別正在辨識的口說語言。 請參閱支援的語言。	必要
format	指定結果格式。 接受的值為 simple 和 detailed。 簡單的結果包含 RecognitionStatus、DisplayText、Offset 和 Duration。 詳細的回應包含四種不同的顯示文字表示法。 預設設定是 simple。	選擇性
profanity	指定如何處理辨識結果中的不雅內容。 接受的值為： masked，這會以星號取代粗話。 removed，這會從結果中移除所有粗話。 raw，這會在結果中包含粗話。 預設設定是 masked。	選擇性
cid	當您使用 Speech Studio 來建立自訂模型時，您可以從 [部署] 頁面利用 [端點識別碼] 值。 使用 [端點識別碼] 作為 cid 查詢字串參數的引數。	選擇性

發音評定參數

下表列出發音評定的必要和選擇性參數：

參數	描述	必要或選用
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	[確定]	要求成功。 回應本文是 JSON 物件。
400	不正確的要求	未提供語言程式碼、不支援語言，或音訊檔案無效 (例如)。
401	未經授權	資源金鑰或授權權杖在指定的區域中無效，或是無效的端點。
403	禁止	遺漏資源金鑰或授權權杖。

回應範例

以下是 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 格式包含下列最上層欄位：

屬性	Description
RecognitionStatus	狀態，例如 Success 代表辨識成功。 請參閱下表。
DisplayText	套用轉換成大寫、標點符號、反向文字正規化及粗話遮罩後所辨識的文字。 只會在成功時呈現。 反向文字正規化是將口語文字轉換成較短的格式，例如 200 表示「two hundred」，或「Dr. Smith」代表「doctor smith」。
Offset	辨識的語音在音訊資料流中開始的時間 (以 100 奈秒為單位)。
Duration	辨識的語音在音訊資料流中的持續時間 (以 100 奈秒為單位)。

RecognitionStatus 欄位可能包含下列的值：

狀態	描述
Success	辨識成功，並顯示 DisplayText 欄位。
NoMatch	音訊串流中偵測到語音，但目標語言中沒有符合的字組。 此狀態通常表示辨識語言與使用者說話的語言不同。
InitialSilenceTimeout	音訊串流的開頭沒有任何聲音，且等候語音時服務已逾時。
BabbleTimeout	音訊串流的開頭只有噪音，且等候語音時服務已逾時。
Error	辨識服務發生內部錯誤，無法繼續。 可能的話，再試一次。

注意

如果音訊只包含不雅內容，而且 profanity 查詢參數設為 remove，則服務不會傳回語音結果。

detailed 格式包含其他形式的辨識結果。 當您使用 detailed 格式時，系統會提供 DisplayText 作為 NBest 清單中每個結果的 Display。

NBest 清單中的物件可包括：

屬性	描述
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) 有助於降低辨識延遲。 這可讓語音服務在音訊檔案傳輸期間開始加以處理。 適用於簡短音訊的 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();
    }
}

驗證

每個要求都需要授權標頭。 下表會列出各項功能支援的標頭：

支援的授權標頭	語音轉換文字	將文字轉換成語音
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。 如果您的訂用帳戶不在美國西部區域，請以您區域的主機名稱取代 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。 請務必使用符合您訂用帳戶區域的正確端點。 此範例目前設為「美國西部」。

$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 (以及適用於 Linux 的 Windows 子系統) 中可用的命令列工具。 此 cURL 命令說明如何取得存取權杖。 使用您的語音服務資源金鑰來取代 YOUR_SUBSCRIPTION_KEY。 請務必使用符合您訂用帳戶區域的正確端點。 此範例目前設為「美國西部」。

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# 類別說明了如何取得存取權杖。 在您具現化類別時，請傳遞您的語音服務資源金鑰。 如果您的訂用帳戶不在美國西部區域，請變更 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 分鐘。 您可以隨時取得新權杖，但為了盡量降低網路流量和延遲，建議您使用相同的權杖九分鐘。

以下是簡短音訊的語音轉換文字 REST API 的 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...

下一步

• 自訂語音模型
• 熟悉批次轉譯