使用需求

當您提出語音辨識要求時，請考量下列基本使用需求：

• 方法名稱會區分大小寫。
• HTTP 要求標頭不區分大小寫。
• HTTP 和 WebSocket 查詢參數會區分大小寫。
• JSON 欄位名稱會區分大小寫。
• 所有 JSON 回應內容都使用 UTF-8 字集。
• 文件中使用括號 ({ }) 表示變量值。 提供變量值時請省略大括號。

另請考量下列服務特定需求：

• 您只需要指定輸入音訊。 所有其他參數都是選用參數。
• 如有必要，請務必指定 model 參數，以指出適合您的語言和音訊的機型。
• 如果您指定無效的查詢參數或 JSON 欄位作為輸入的一部分，回應會包含 warnings 欄位，說明無效的引數。 無論有任何警告，要求都會成功。

使用要求傳送音訊

您傳遞給服務的音訊必須使用服務的其中一個支援格式。 對於大部分音訊而言，此服務可以自動偵測格式。 對於部分音訊，您必須使用 Content-Type 或相等參數來指定格式。 如需相關資訊，請參閱音訊格式。 （為了清晰表達，下列範例會指定所有要求的音訊格式。）

使用 WebSocket 介面和同步 HTTP 介面，您可以使用單一要求來傳遞最多 100 MB 的音訊資料。 透過非同步 HTTP 介面，最多可以傳遞 1 GB 的音訊資料。 在任何要求中，您必須至少傳送 100 個位元組的音訊。

如果您要辨識大量音訊，可以手動將音訊分割成較小的片段。 然而，將音訊轉換為壓縮的失真格式通常會更有效率且方便。 壓縮可以讓單一要求中可傳送的音訊資料量達到最大。 尤其如果音訊是 WAV 或 FLAC 格式，將其轉換為失真格式將會有明顯的差異。

• 有關使用壓縮的音訊格式的詳細資訊，請參閱 音訊格式。
• 如需壓縮效果及將音訊轉換為使用它之格式的相關資訊，請參閱資料限制和壓縮和音訊轉換。
• 如需從同時包含音訊和視訊的多媒體檔案轉錄音訊的相關資訊，請參閱從視訊檔轉錄語音。

使用 WebSocket 介面

WebSocket 介面提供有效的實作，透過全雙工連線提供低延遲及高傳輸量。 所有要求和回應都透過相同的 WebSocket 連線傳送。

若要使用 WebSocket 介面，首先請使用 /v1/recognize 方法來建立與服務的連線。 您可以指定要用於透過連線傳送之要求的參數，例如語言模型和任何自訂模型。 然後，您將登錄事件接聽器，以處理來自服務的回應。 若要提出要求，您可以傳送包含音訊格式及任何其他參數的 JSON 文字訊息。 您以二進位訊息（二進位大型物件）傳遞音訊，然後傳送文字訊息以指出音訊結束。

下列範例提供 JavaScript 程式碼來建立連線，並傳送用於辨識要求的文字和二進位訊息。 基本範例不包含定義連線所有必要事件處理程式的程式碼。

var access_token = {access_token};
var wsURI = '{ws_url}/v1/recognize'
  + '?access_token=' + access_token;
var websocket = new WebSocket(wsURI);

websocket.onopen = function(evt) { onOpen(evt) };

function onOpen(evt) {
  var message = {
    action: 'start',
    content-type: 'audio/flac'
  };
  websocket.send(JSON.stringify(message));
  websocket.send(blob);
  websocket.send(JSON.stringify({action: 'stop'}));
}

使用同步 HTTP 介面

同步 HTTP 介面提供最簡單的方法來提出辨識要求。 您可以使用 POST /v1/recognize 方法對服務提出要求。 您使用單一要求來傳遞音訊及所有參數。 下列 curl 範例顯示基本 HTTP 辨識要求：

IBM Cloud

curl -X POST -u "apikey:{apikey}" \
--header "Content-Type: audio/flac" \
--data-binary @audio-file.flac \
"{url}/v1/recognize"

IBM Cloud Pak for Data IBM Software Hub

curl -X POST \
--header "Authorization: Bearer {token}" \
--header "Content-Type: audio/flac" \
--data-binary @audio-file.flac \
"{url}/v1/recognize"

使用非同步 HTTP 介面

非同步 HTTP 介面提供非區塊處理介面來轉錄音訊。 無論是否先向服務登錄回呼 URL，您都可以使用此介面。 使用回呼 URL，該服務會傳回含有工作狀態和辨識結果的回呼通知。 該介面會根據使用者指定的密碼來使用 HMAC-SHA1 簽章，為其通知提供鑑別和資料完整性。 若沒有回呼 URL，您必須輪詢該服務，才能取得工作狀態和結果。 不論哪一種方法，您都可以使用 POST /v1/recognitions 方法來提出辨識要求。

下列 curl 範例顯示簡易非同步 HTTP 辨識要求。 此要求不包括回呼 URL，因此您必須輪詢服務，以取得工作狀態和產生的文字記錄。

IBM Cloud

curl -X POST -u "apikey:{apikey}" \
--header "Content-Type: audio/flac" \
--data-binary @audio-file.flac \
"{url}/v1/recognitions"

IBM Cloud Pak for Data IBM Software Hub

curl -X POST \
--header "Authorization: Bearer {token}" \
--header "Content-Type: audio/flac" \
--data-binary @audio-file.flac \
"{url}/v1/recognitions"