用法需求

发出语音识别请求时，请考虑以下基本用法需求：

• 方法名称区分大小写。
• 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 文本消息。 可将音频作为二进制消息 (blob) 传递，然后发送文本消息以指示音频结束。

以下示例提供的 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"