使用語音轉文字 REST API 來錄製短音頻

只有在無法使用 Speech SDK 或 快速轉錄 API 的情況下，才用語音轉文字 REST API 來播放短音頻。

在使用語音轉文字 REST API 進行短音頻之前，請考慮以下限制：

• 使用 REST API 進行短音訊並直接傳送音訊的請求，音訊長度不得超過 60 秒。 發音評估時，音訊長度不應超過30秒。 輸入 音訊格式 比 Speech SDK 限制更多。
• 短音頻的 REST API 只會回傳最終結果。 它不會提供部分結果。
• 短音頻的 REST API 不支援語音翻譯。 你需要使用 Speech SDK。
• REST API 不支援針對短音頻的批次轉錄和自訂語音。 你應該一直使用 Speech to text REST API 來批次轉錄和自訂語音。

在使用語音轉文字 REST API 進行短音頻之前，請了解你需要完成憑證交換作為認證的一部分，才能存取該服務。 更多資訊請參閱 認證。

區域與終點

短音頻的 REST API 端點格式如下：

https://YourResourceName.cognitiveservices.azure.com/stt/speech/recognition/conversation/cognitiveservices/v1

用你的語音資源名稱來替代 YourResourceName 。

註

關於由21Vianet端點操作的Azure Government與Microsoft Azure，請參見關於主權雲的文章。

音訊格式

音訊會傳送在 HTTP POST 請求的正文中。 必須是本表中的某一種格式：

格式	編解碼器	位元率	取樣率
WAV	PCM	256 kbps	16 kHz，單聲道
OGG	OPUS	256 kbps	16 kHz，單聲道

註

Speech 服務中的 REST API (適用於短音訊) 和 WebSockets 支援上述格式。 語音 SDK 支援 WAV 格式及 PCM 編解碼器及其他格式。

請求標頭

此表列出語音轉文字請求的必用與可選標頭：

標頭	描述	必修或選修
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。 Speech 服務提供 JSON 格式的結果。 有些請求框架會提供不相容的預設值。 務必包含 Accept。	可選，但建議這麼做。

查詢參數

這些參數可能會包含在 REST 請求的查詢字串中。

註

你必須在網址後加上語言參數，以避免收到 4xx HTTP 錯誤。 例如，將語言設為美式英文的設定為：https://YourResourceName.cognitiveservices.azure.com/stt/speech/recognition/conversation/cognitiveservices/v1?language=en-US。

參數	描述	必修或選修
language	辨識被識別的口語語言。 參見 支援語言。	必需的
format	指定結果格式。 公認的值為 simple 和 detailed。 簡單結果包括 RecognitionStatus、 DisplayText、 Offset和 Duration。 詳細回應包含四種不同的顯示文字表示方式。 預設設定為 simple。	可選
profanity	說明如何處理識別結果中的髒話。 公認的數值如下： masked，該詞將髒話替換為星號。 removed，結果中刪除了所有髒話。 raw，結果中包含髒話。 預設設定為 masked。	可選

發音評估參數

此表列出發音評估所需的與可選參數：

參數	描述	必修或選修
ReferenceText	用於發音評估的文本。	必需的
GradingSystem	校準分數的積點系統 FivePoint 系統給予的浮點分數範圍為0到5，HundredMark 的則為0到100。 預設值： FivePoint。	可選
Granularity	評估的細緻程度。 公認的數值如下： Phoneme，顯示全文、單字和音素層級的分數。 Word，顯示全文和詞彙層級的分數。 FullText，僅顯示全文層級的分數。 預設設定為 Phoneme。	可選
Dimension	定義輸出標準。 公認的數值如下： 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 狀態碼	描述	可能原因
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": 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 包含以下頂層字段：

財產	描述
RecognitionStatus	狀態，例如 Success 代表辨識成功。 請參考下一張表格。
DisplayText	經過大寫、標點、反向正規化及髒話遮蔽程序後，識別出的文字。 只有成功時才會現身。 反向文字正規化是將口語文字轉換為較短的形式，例如將「兩百」轉換成「200」，或將「史密斯醫生」轉換成「Dr. Smith」。
Offset	識別語音在音訊串流中開始的時間（單位為100奈秒）。
Duration	音訊串流中識別語音的持續時間（單位為100奈秒）。
SNR	音訊串流中識別語音的訊噪比（SNR）。

欄位 RecognitionStatus 可能包含以下數值：

現況	描述
Success	識別成功，且 DisplayText 欄位存在。
NoMatch	語音串流中偵測到語音，但目標語言的詞彙未匹配。 此狀態通常表示識別語言與使用者所使用的語言不同。
InitialSilenceTimeout	音訊串流的開頭沒有任何聲音，且等候語音時服務已逾時。
BabbleTimeout	音訊串流的開頭只有噪音，且等候語音時服務已逾時。
Error	識別服務遇到內部錯誤，無法繼續。 如果可能的話再試一次。

註

如果音訊僅包含髒話，且 profanity 查詢參數設為 remove，該服務不會回傳語音結果。

此 detailed 格式包含更多類型的確認結果。 當您使用 detailed 格式時，系統會提供 DisplayText 作為 Display 清單中每個結果的 NBest。

清單中的 NBest 物件可以包括：

財產	描述
Confidence	項目的信賴分數從 0.0 (不信賴) 到 1.0 (完全信賴)。
Lexical	已識別文本的詞彙形式：即實際被識別的詞彙。
ITN	已辨識文字的反向文字正規化 (ITN) 或標準形式，包含電話號碼、數字、縮寫 ("doctor smith" 縮短為 "dr smith")，以及其他已套件的轉換。
MaskedITN	如果要求，已套用不雅內容遮罩的 ITN 形式。
Display	已識別文本的顯示形式，加上大寫和標點符號。 此參數與將格式設為 DisplayText 時，simple 所提供的參數相同。
AccuracyScore	演講的發音準確度。 準確性表示音素與母語者的發音有多接近。 單字與全文層級的準確度分數是從音位層級的準確度分數彙總而來。
FluencyScore	所提供語言的流暢度。 流暢度表示該語言與母語者在詞間靜默段落的使用有多接近。
ProsodyScore	演講韻律。 韻律表示指定語音的自然度，包括重音、語調、語速和節奏。 欲詳細查看韻律評估結果的定義，請參閱 結果參數。
CompletenessScore	語音完整性，透過計算發音詞彙與參考文字輸入的比例來判斷。
PronScore	總分數顯示所提供語音的發音品質。 此分數由AccuracyScore、FluencyScore及CompletenessScore依權重彙總而成。
ErrorType	指示詞語是否被省略、插入或發音不佳的值，並與 ReferenceText 進行比較。 可能的值為None（此詞無誤）、Omission、、 InsertionMispronunciation。

分塊傳輸

分塊傳輸（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	是的	是的
Authorization: Bearer	是的	是的

使用 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
• 自訂語音模型
• 熟悉批次轉錄