异步 HTTP 接口
异步 HTTP 接口是一个用于将长时间音频转换为文本、进行文字转录的非阻塞 HTTP API。
要使用此 API，请执行以下步骤：
- 创建语音识别任务
- 轮询检查语音识别任务的状态并获取结果
步骤 1 中生成任务的方法与同步 HTTP 接口基本相同，只是在指定是否保存日志等方面略有不同。
endpoint
与同步 HTTP 接口不同，无论是否保存日志，endpoint 的基础都是相同的。
https://acp-api-async.amivoice.com/v1/recognitions
1. 创建任务
Endpoint：
POST https://acp-api-async.amivoice.com/v1/recognitions
请求
请求方法与同步 HTTP 接口相同。有关详细信息，请参阅同步 HTTP 接口参考中的请求。
关于 d 参数
可以设置同步 HTTP 接口的d 参数。仅在异步 HTTP 接口中有效的参数如下表所示。
| 参数名 | 值 | 说明 |
|---|---|---|
| loggingOptOut | True|False | 指定是否更改日志保存。设置为 True 时，系统在会话期间不会保存日志。默认为 False。 |
| contentId | 任意字符串 | 可以指定用户定义的任意字符串。它将包含在该会话期间的状态和结果响应中。默认情况下不设置。 |
| compatibleWithSync | True|False | 结果格式的兼容性。以与同步 HTTP 接口兼容的形式格式化结果。默认为 False。 |
| speakerDiarization | True|False | 说话人区分启用选项。启用说话人区分。默认为 False。 |
| diarizationMinSpeaker | int | 说话人区分的最小推测说话人数。仅在启用说话人区分时有效，可以指定音频中包含的最小说话人数。需要设置为 1 或更大。默认为 1。 |
| diarizationMaxSpeaker | int | 说话人区分的最大推测说话人数。仅在启用说话人区分时有效，可以指定音频中包含的最大说话人数。需要设置为大于或等于 diarizationMinSpeaker。默认为 10。 |
| sentimentAnalysis | True|False | 启用情绪分析。默认为 False。 |
响应
成功时的响应以 JSON 格式包含以下值。
| key | 说明 |
|---|---|
| sessionid | 用户语音识别请求的任务 ID。 |
| text | 始终返回...。 |
示例
{"sessionid":"017ac8786c5b0a0504399999","text":"..."}
失败时的响应以 JSON 格式包含以下值。
| key | 说明 | |
|---|---|---|
| results | 数组(1 个元素) | |
| tokens | 数组(空) | |
| tags | 数组(空) | |
| rulename | 字符串(空) | |
| text | 字符串(空) | |
| text | 字符串(空) | |
| code | 表示结果的 1 个字符代码。请参阅响应代码和消息。 | |
| message | 表示错误内容的字符串。请参阅响应代码和消息。 |
示例
{
"results": [{ "tokens": [], "tags": [], "rulename": "", "text": "" }],
"text": "",
"code": "-",
"message": "received illegal service authorization"
}
2. 检查任务状态、获取结果
Endpoint：
GET https://acp-api-async.amivoice.com/v1/recognitions/{session_id}
请求
请求参数
| 参数名 | 必须 | 发送方法 | 说明 |
|---|---|---|---|
| session_id | ● | 路径参数 | 指定创建任务响应中获得的 ID。 |
认证
请在 Authorization header 中指定 APPKEY。
Authorization: Bearer {APPKEY}
响应
如果请求成功，将返回语音识别请求的状态 status 和相关信息。如果失败，将返回 HTTP 响应代码 200 以外的值。成功时的 status 可能有以下 5 个值：
| status | 说明 |
|---|---|
| queued | 任务已注册到队列中的状态。 |
| started | 任务已从队列中取出，正在准备执行环境的状态。 |
| processing | 任务正在执行的状态。 |
| completed | 已从语音识别过程获得结果的状态。如果 code 为空字符串，即语音识别成功，结果将包含在 segments 中。 |
| error | 尝试执行任务时或任务执行过程中发生某些错误的状态。错误详细信息保存在 error_message 中。 |
响应中包含的信息
下表总结了 queued、started、processing、completed 和 error 各状态下包含的信息。在每个状态的首字母列(q, s, p, c, e)中，A 表示始终包含，O 表示如果有该信息则包含在响应中。
| key | q | s | p | c | e | 说明 |
|---|---|---|---|---|---|---|
| status | A | A | A | A | A | 任务状态。可能为 queued、started、processing、completed 或 error。 |
| audio_md5 | A | A | O | 接收到的音频文件的 MD5 校验和值。 | ||
| audio_size | A | A | O | 接收到的音频文件的大小。 | ||
| content_id | O | O | O | O | O | 用户在请求时设置的 contentId 值。 |
| service_id | A | A | A | A | userId。 | |
| segments | A | 语音识别过程的结果。按发话单位的语音识别结果。 | ||||
| utteranceid | A | 语音识别过程的结果。识别结果信息 ID。 | ||||
| text | A | 语音识别过程的结果。所有"发言区间识别结果"连接的整体识别结果文本。 | ||||
| code | A | 语音识别过程的结果。表示结果的 1 个字符代码。 | ||||
| message | A | 语音识别过程的结果。表示错误内容的字符串。 | ||||
| error_message | A | 表示错误内容的字符串 |
completed(语音识别结果)响应的详细信息
当 status 为 completed 时，将以 JSON 格式返回语音识别结果。与同步 HTTP 接口不同，识别结果按发话单位放置在 segments 下。
| 说明 | ||||
|---|---|---|---|---|
| segments | ||||
| results | "发言区间识别结果"数组 | |||
| confidence | 置信度(0 到 1 之间的值。0：置信度低，1：置信度高) | |||
| starttime | 发话开始时间(音频数据开头为 0) | |||
| endtime | 发话结束时间(音频数据开头为 0) | |||
| tags | 未使用(空数组) | |||
| rulename | 未使用(空字符串) | |||
| text | 识别结果文本 | |||
| tokens | 识别结果文本的形态素数组 | |||
| written | 形态素(单词)的显示 | |||
| confidence | 形态素的置信度(识别结果的似然度) | |||
| starttime | 形态素的开始时间(音频数据开头为 0) | |||
| endtime | 形态素的结束时间(音频数据开头为 0) | |||
| spoken | 形态素的读音 | |||
| label | 说话人标签(speaker0, speaker1, ...)仅当请求时指定 speakerDiarization=True 时，结果中才包含此项。 | |||
| utteranceid | 识别结果信息 ID | |||
| text | 所有"发言区间识别结果"连接的整体识别结果文本 | |||
| code | 表示结果的 1 个字符代码。请参阅响应代码和消息。 | |||
| message | 表示错误内容的字符串。请参阅响应代码和消息。 |
error(错误)响应的详细信息
以下是语音识别处理失败时的响应示例。每个值的说明请参阅响应中包含的信息。
示例
{
"status": "error",
"audio_md5":"40f59fe5fc7745c33b33af44be43f6ad",
"audio_size":306980,
"service_id":"{YOUR_SERVICE_ID}",
"session_id":"017c25ec12c00a304474a999",
"error_message": "ERROR: Failed to transcribe in recognition process - amineth_result=0, amineth_code='o', amineth_message='recognition result is rejected because confidence is below the threshold'"
}
错误响应
如果检查任务状态、获取结果的 endpoint 调用失败，将返回 HTTP 状态码 200 以外的值。响应正文将返回包含以下信息的 JSON 数据。
| 参数名 | 说明 |
|---|---|
| errorCode | 响应代码。 |
| errorMessage | 错误消息。 |
示例:
{
"errorCode":401,
"errorMessage":"Invalid authorization header format"
}
状态码和错误消息
调用失败时的状态码和错误消息如下：
| HTTP 状态码 | 错误消息 | 说明 |
|---|---|---|
| 401 | No app_key | 未设置 APPKEY |
| 401 | No authorization header | 未设置 Authorization header |
| 401 | Invalid authorization header format | Authorization header 格式不正确 |
| 401 | Failed to authorize for the app_key | 使用指定的 APPKEY 进行认证失败 |
| 404 | Specified session_id is not found | 找不到指定的 session_id 的任务。如果指定了正确的 session_id 但仍出现此错误，可能是以下情况：- 超过数据保存期限 - 与请求时不同的用户尝试获取任务状态或结果 |
| 500 | - | 内部错误。请联系我们。 |