要使用 IBM Watson® Speech to Text 服务请求语音识别,您只需提供要转录的音频。 服务为其每个接口(WebSocket 接口、同步 HTTP 接口和异步 HTTP 接口)提供了相同的基本转录功能。
以下示例显示了每个服务接口的基本转录请求 (不含可选参数):
- 这些示例将提交名为 audio-file.flac的简短 FLAC 文件。
- 示例使用缺省语言模型
en-US_BroadbandModel
。 有关更多信息,请参阅 使用缺省模型。
了解语音识别结果 描述服务对这些示例的响应。
用法需求
发出语音识别请求时,请考虑以下基本用法需求:
- 方法名称区分大小写。
- 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
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
curl -X POST --header "Authorization: Bearer {token}" --header "Content-Type: audio/flac" --data-binary @audio-file.flac "{url}/v1/recognitions"