短音頻的語音轉文字 REST API - 語音服務 - Foundry Tools

區域與終點

短音頻的 REST API 端點格式如下：
https://YourResourceName.cognitiveservices.azure.com/stt/speech/recognition/conversation/cognitiveservices/v1
用你的語音資源名稱來替代 YourResourceName 。
關於由21Vianet端點操作的Azure Government與Microsoft Azure，請參見關於主權雲的文章。
音訊會傳送在 HTTP POST 請求的正文中。 必須是本表中的某一種格式：
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。 Speech 服務提供 JSON 格式的結果。 有些請求框架會提供不相容的預設值。 務必包含 Accept。
可選，但建議這麼做。
這些參數可能會包含在 REST 請求的查詢字串中。
你必須在網址後加上語言參數，以避免收到 4xx HTTP 錯誤。 例如，將語言設為美式英文的設定為：https://YourResourceName.cognitiveservices.azure.com/stt/speech/recognition/conversation/cognitiveservices/v1?language=en-US。
format
指定結果格式。 公認的值為 simple 和 detailed。 簡單結果包括 RecognitionStatus、 DisplayText、 Offset和 Duration。 詳細回應包含四種不同的顯示文字表示方式。 預設設定為 simple。
profanity
說明如何處理識別結果中的髒話。 公認的數值如下： 


              masked，該詞將髒話替換為星號。 

              removed，結果中刪除了所有髒話。 

              raw，結果中包含髒話。 

預設設定為 masked。
發音評估參數
此表列出發音評估所需的與可選參數：
必修或選修
定義輸出標準。 公認的數值如下：

 
              Basic，僅顯示準確度分數。 

              Comprehensive，顯示更多維度的分數（例如全文層級的流暢度分數與完整性分數，以及單字層級的錯誤類型）。

 欲了解不同分數維度及詞錯類型的定義，請參閱 反應屬性。 預設設定為 Basic。
EnableMiscue
啟用誤讀計算。 啟用此參數後，發音詞彙會與參考文本進行比較。 根據比較結果，會以省略或插入標示。 公認的值為 False 和 True。 預設設定為 False。
EnableProsodyAssessment
為您的發音評估啟用韻律評量。 此功能會評估重音、語調、語速與節奏等方面。 此功能能讓你了解你說話的自然與表現力。

 若將此屬性設為 True， ProsodyScore 則返回結果值。
ScenarioId
一個表示自訂點數系統的 GUID。
這裡有包含發音評估參數的 JSON 範例：
  "ReferenceText": "Good morning.",
  "GradingSystem": "HundredMark",
  "Granularity": "Word",
  "Dimension": "Comprehensive",
  "EnableProsodyAssessment": "True"
以下範例程式碼說明如何在標頭中建立發音評估參數 Pronunciation-Assessment ：
var pronAssessmentParamsJson = $"{{\"ReferenceText\":\"Good morning.\",\"GradingSystem\":\"HundredMark\",\"Granularity\":\"Word\",\"Dimension\":\"Comprehensive\",\"EnableProsodyAssessment\":\"True\"}}";
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: YourResourceName.cognitiveservices.azure.com
Transfer-Encoding: chunked
Expect: 100-continue
為了啟用發音評估，你可以加上以下標頭。 想了解如何建立這個標頭，請參閱 發音評估參數。
Pronunciation-Assessment: eyJSZWZlcm...
HTTP 狀態碼
每個回應的 HTTP 狀態碼表示成功或常見錯誤。
HTTP 狀態碼
  "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": 700000,
  "Duration": 8400000,
  "DisplayText": "Good morning.",
  "SNR": 38.76819,
  "NBest": [
      "Confidence": 0.98503506,
      "Lexical": "good morning",
      "ITN": "good morning",
      "MaskedITN": "good morning",
      "Display": "Good morning.",
      "AccuracyScore": 100.0,
      "FluencyScore": 100.0,
      "ProsodyScore": 87.8,
      "CompletenessScore": 100.0,
      "PronScore": 95.1,
      "Words": [
          "Word": "good",
          "Offset": 700000,
          "Duration": 2600000,
          "Confidence": 0.0,
          "AccuracyScore": 100.0,
          "ErrorType": "None",
          "Feedback": {
            "Prosody": {
              "Break": {
                "ErrorTypes": [
                  "None"
                "BreakLength": 0
              "Intonation": {
                "ErrorTypes": [],
                "Monotone": {
                  "Confidence": 0.0,
                  "WordPitchSlopeConfidence": 0.0,
                  "SyllablePitchDeltaConfidence": 0.91385907
          "Word": "morning",
          "Offset": 3400000,
          "Duration": 5700000,
          "Confidence": 0.0,
          "AccuracyScore": 100.0,
          "ErrorType": "None",
          "Feedback": {
            "Prosody": {
              "Break": {
                "ErrorTypes": [
                  "None"
                "UnexpectedBreak": {
                  "Confidence": 3.5294118e-08
                "MissingBreak": {
                  "Confidence": 1.0
                "BreakLength": 0
              "Intonation": {
                "ErrorTypes": [],
                "Monotone": {
                  "Confidence": 0.0,
                  "WordPitchSlopeConfidence": 0.0,
                  "SyllablePitchDeltaConfidence": 0.91385907
結果以 JSON 格式提供。 格式 simple 包含以下頂層字段：
DisplayText
經過大寫、標點、反向正規化及髒話遮蔽程序後，識別出的文字。 只有成功時才會現身。 反向文字正規化是將口語文字轉換為較短的形式，例如將「兩百」轉換成「200」，或將「史密斯醫生」轉換成「Dr. Smith」。
Offset
識別語音在音訊串流中開始的時間（單位為100奈秒）。
Duration
音訊串流中識別語音的持續時間（單位為100奈秒）。
音訊串流中識別語音的訊噪比（SNR）。
欄位 RecognitionStatus 可能包含以下數值：
分塊傳輸（Transfer-Encoding: chunked）能幫助降低辨識延遲。 它允許語音服務在音訊檔案傳輸時開始處理。 短音頻的 REST API 不會提供部分或中期結果。
以下程式碼範例展示了如何分段傳送音訊。 只有第一個區塊應該包含音訊檔案的標頭。 
              request 是一個 HttpWebRequest 連接到相應 REST 端點的物件。 
              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 標頭時，必須只提供你的資源金鑰。 例如：
'Ocp-Apim-Subscription-Key': 'YourSpeechResourceKey'
如果您使用 STS 持有人權杖流程搭配Authorization: Bearer，請先對issueToken端點提出要求。 在此要求中，要以資源金鑰交換有效期間 10 分鐘的存取權杖。
另一種選擇是使用 Microsoft Entra 認證，也使用 Authorization: Bearer 標頭，但憑證由 Microsoft Entra ID 發出。 參見 Use Microsoft Entra authentication。
如何取得 STS 存取令牌
要取得 STS 存取權杖，請使用 issueToken 和 你的資源金鑰向Ocp-Apim-Subscription-Key端點提出請求。
              issueToken端點格式如下：
https://YourResourceName.cognitiveservices.azure.com/sts/v1.0/issueToken
用你的語音資源名稱來替代 YourResourceName 。
這個端點需要你的資源設定 自訂子網域 。 對於沒有自訂網域的資源，請改用區域端點： https://<region>.api.cognitive.microsoft.com/sts/v1.0/issueToken。 將 <region> 替換成資源的Azure區域（例如 eastus）。
請使用以下範例來建立您的存取權憑證申請。
HTTP 範例
這個例子是一個簡單的 HTTP 請求，用來取得一個 token。 用你的語音服務資源金鑰替換 YourSpeechResourceKey 。 用你的語音資源名稱來替代 YourResourceName 。
POST /sts/v1.0/issueToken HTTP/1.1
Ocp-Apim-Subscription-Key: YourSpeechResourceKey
Host: YourResourceName.cognitiveservices.azure.com
Content-type: application/x-www-form-urlencoded
Content-Length: 0
回應正文包含以 JSON Web Token （JWT） 格式呈現的存取權杖。
PowerShell 範例
這個範例是一個簡單的 PowerShell 腳本，用來取得存取權杖。 用你的語音服務資源金鑰替換 YourSpeechResourceKey 。 用你的語音資源名稱來替代 YourResourceName 。
$FetchTokenHeader = @{
  'Content-type'='application/x-www-form-urlencoded';
  'Content-Length'= '0';
  'Ocp-Apim-Subscription-Key' = 'YourSpeechResourceKey'
$OAuthToken = Invoke-RestMethod -Method POST `
    -Uri https://YourResourceName.cognitiveservices.azure.com/sts/v1.0/issueToken `
    -Headers $FetchTokenHeader
# show the token received
$OAuthToken
cURL 範例
cURL 是一個在 Linux（以及 Windows 子系統 Linux 版）中使用的命令列工具。 這個 cURL 指令說明如何取得存取權杖。 用你的語音服務資源金鑰替換 YourSpeechResourceKey 。 用你的語音資源名稱來替代 YourResourceName 。
curl -v -X POST \
 "https://YourResourceName.cognitiveservices.azure.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# 類別示範了如何取得存取權杖。 在實例化類別時，傳遞語音服務的資源金鑰。 用你的語音資源名稱來替代 YourResourceName 。
public class Authentication
    public static readonly string FetchTokenUri =
        "https://YourResourceName.cognitiveservices.azure.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://YourResourceName.cognitiveservices.azure.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分鐘。 你可以隨時取得新的令牌，但為了減少網路流量和延遲，我們建議使用相同的令牌九分鐘。
Important
持有人權杖的範圍是核發它們的端點。 從YourResourceName.cognitiveservices.azure.com取得的權杖只對同一主機的要求有效。 來自 <region>.api.cognitive.microsoft.com 的權杖只能用於區域性 Speech 端點。 如果您在使用 Bearer 權杖時收到 401 錯誤，請改用 Ocp-Apim-Subscription-Key 搭配您的資源金鑰，這種方式適用於所有端點格式。
以下是短音頻對語音轉文字 REST API 的 HTTP 請求範例：
POST /cognitiveservices/v1 HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN
Host: YourResourceName.cognitiveservices.azure.com
Content-type: application/ssml+xml
Content-Length: 199
Connection: Keep-Alive
// Message body here...
使用 Microsoft Entra 認證
要使用 Microsoft Entra 認證搭配語音轉文字 REST API 來錄製短音頻，你需要建立一個存取權杖。
取得包含資源 ID 與 Microsoft Entra 存取權杖的步驟與使用 Speech SDK 相同。
請依照此處步驟使用 Microsoft Entra 認證
建立語音鑄造資源
設定語音資源以進行 Microsoft Entra 認證
取得 Microsoft Entra 存取令牌
取得語音資源ID
取得資源 ID 與 Microsoft Entra 存取權杖後，實際的存取權杖可依以下格式建構：
aad#YOUR_RESOURCE_ID#YOUR_MICROSOFT_ENTRA_ACCESS_TOKEN
你需要在資源識別碼和存取權杖之間加入「aad#」前綴和「#」（哈希）分隔符。
以下是短音頻對語音轉文字 REST API 的 HTTP 請求範例：
POST /cognitiveservices/v1 HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN
Host: YourResourceName.cognitiveservices.azure.com
Content-type: application/ssml+xml
Content-Length: 199
Connection: Keep-Alive
// Message body here...
欲了解更多關於 Microsoft Entra 存取權杖的資訊，包括權杖壽命，請造訪 Microsoft 身分識別平台中的存取權杖。
              快速轉錄 API
              自訂語音模型
              熟悉批次轉錄