簡短音訊的語音轉換文字 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 以及由 21Vianet 營運的 Microsoft Azure 端點相關資訊，請參閱關於主權雲端的文章。

音訊格式

音訊會在 HTTP POST 要求的本文中傳送。 它必須是此表格中的其中一種格式：

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

注意

上述格式是透過語音服務中的簡短音訊和 WebSocket 的 REST API 支援。 語音 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 包含下列最上層欄位：

屬性	說明
RecognitionStatus	狀態，例如 Success 成功辨識。 請參閱下一個表格。
DisplayText	大寫、標點符號、反文字正規化和粗話遮罩之後辨識的文字。 只有在成功時才會出現。 反向文字正規化是將口語文字轉換成較短的形式，例如“二百”或“史密斯博士”為“醫生史密斯”。
Offset	在音訊數據流中開始辨識語音的時間（以 100 奈秒為單位）。
Duration	音訊數據流中已辨識語音的持續時間（以100奈秒為單位）。

欄位 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	提供的語音流暢。 流暢度指出語音與母語人士在字組間停頓的相符程度。
CompletenessScore	語音完整性，由計算發音文字與參考文字輸入的比例來決定。
PronScore	表示所提供語音發音質量的整體分數。 此分數會從 AccuracyScore、 FluencyScore和 以 CompletenessScore 權數匯總。
ErrorType	值，指出與相較之下 ReferenceText，是否省略、插入或發音錯誤的單字。 可能的值為 None （表示這個字組沒有任何錯誤）、 Omission、 Insertion和 Mispronunciation。

區塊傳輸

區塊傳輸 （Transfer-Encoding: chunked） 有助於降低辨識延遲。 它可讓語音服務在傳輸時開始處理音訊檔案。 簡短音訊的 REST API 不提供部分或過渡結果。

下列程式代碼範例示範如何以區塊傳送音訊。 只有第一個區塊應該包含音訊檔案的標頭。 requestHttpWebRequest是連接到適當 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	Yes	.是
Authorization: Bearer	.是	Yes

當您使用 Ocp-Apim-Subscription-Key 標頭時，必須只提供您的資源密鑰。 例如：

'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'

當您使用 Authorization: Bearer 標頭時，您必須對 issueToken 端點提出要求。 在此要求中，您會將資源密鑰交換為有效 10 分鐘的存取令牌。

另一個選項是使用Microsoft Entra 驗證，該驗證也會使用 Authorization: Bearer 標頭，但具有透過 Microsoft Entra ID 簽發的令牌。 請參閱 使用Microsoft Entra 驗證。

如何取得存取權杖

若要取得存取令牌，您必須使用 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 中可用的命令行工具（以及 Windows 子系統 Linux 版）。 這個 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分鐘。 您可以隨時取得新的令牌，但若要將網路流量和延遲降到最低，我們建議在 9 分鐘內使用相同的令牌。

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

使用 Microsoft Entra 驗證

若要使用 Microsoft Entra 驗證搭配語音轉換文字 REST API 進行簡短音訊，您必須建立存取令牌。 取得由資源標識碼和Microsoft Entra 存取令牌所組成的存取令牌的步驟，與使用語音 SDK 時的步驟相同。 請遵循這裡的 步驟使用 Microsoft Entra 驗證

• 建立語音資源
• 設定 Microsoft Entra 驗證的語音資源
• 取得 Microsoft Entra 存取權杖
• 取得語音資源識別碼

取得資源標識碼和Microsoft Entra 存取令牌之後，可以依照下列格式建構實際的存取令牌：

aad#YOUR_RESOURCE_ID#YOUR_MICROSOFT_ENTRA_ACCESS_TOKEN

您必須在資源標識碼與存取令牌之間包含 “aad#” 前置詞和 “#” （hash） 分隔符。

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

若要深入了解 Microsoft Entra 存取權杖，包括權杖存留期，請瀏覽 Microsoft 身分識別平台中的存取權杖。

下一步

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