关键词检索

简介

HI,您好,欢迎使用腾讯AI开放平台关键词检索API接口服务。

本文档主要针对需要集成HTTP API的技术研发工程师,详细描述关键词检索能力相关的技术内容。

如果您对文档内容有任何疑问,可以通过以下几种方式联系我们:

官方交流一群:581197347

官方交流二群:705874401

官方交流三群:415349651

联系邮箱:aicamp@tencent.com

接口能力

接口名称 接口描述 API地址
关键词检索 上传长音频,提供回调接口,异步获取识别结果 https://api.ai.qq.com/fcgi-bin/aai/aai_detectkeyword

更多更强大的接口能力正在开发中,并逐步开放,敬请期待!

协议须知

调用方集成关键词检索API时,请遵循以下规则。

规则 描述
传输方式 HTTPS
请求方法 POST
语音参数 必须符合8K采样率、16bit采样位数、单声道
语音格式 PCM、WAV、AMR、 SILK
字符编码 统一采用UTF-8编码
响应格式 统一采用JSON格式
接口鉴权 签名机制,详情请阅接口鉴权

关键词检索

关键词检索包含两个接口:语音上传接口,回调接口。用户调用语音上传接口上传语音,返回task_id,在识别完成后平台异步通知用户,返回识别结果。

1. 语音上传接口描述

用户调用语音上传接口上传语音,返回task_id。

请注意单次请求中,以文件形式直接上传时音频大小不超过5M,以音频链接上传时音频大小不超过30M,时长建议在15分钟以内。

只支持中文普通话关键词检索,后续开放更多语种的识别能力。

2. 语音上传请求参数

参数名称 是否必选 数据类型 数据约束 示例数据 描述
app_id int 正整数 1000001 应用标识(AppId)
time_stamp int 正整数 1493468759 请求时间戳(秒级)
nonce_str string 非空且长度上限32字节 fa577ce340859f9fe 随机字符串
sign string 非空且长度固定32字节 签名信息,详见接口鉴权
format int 正整数 1 语音压缩格式编码,定义见下文描述
callback_url string 非空 ... 用户回调url,需用户提供,用于平台向用户通知识别结果,详见下文描述
key_words string 非空,多个关键词之间用“|”分隔,每个词长度不低于两个字,上限500个词 天气 待识别关键词
speech string 语音数据的Base64编码,原始音频大小上限5MB ... 待识别语音(时长上限15min)
speech_url string 音频下载地址,音频大小上限30MB ... 待识别语音下载地址(时长上限15min)

speech 和 speech_url 二选一,如果两个参数都提供,优先使用speech。

语音压缩格式编码

格式名称 格式编码
PCM 1
WAV 2
AMR 3
SILK 4

3. 语音上传响应参数

参数名称 是否必选 数据类型 描述
ret int 返回码; 0表示成功,非0表示出错
msg string 返回信息;ret非0时表示出错时错误原因
data object 返回数据;ret为0时有意义
+ task_id string 本次识别任务ID

4. 参考示例

假设示例请求数据如下。

参数名称 参数数据 描述
app_id 1000001 仅供参考
format 1 仅供参考
callback_url https://ai.qq.com 仅供参考
speech 实时计算base64
key_words 天气 仅供参考
time_stamp 实时计算
nonce_str 实时计算
sign 实时计算

假设应用密钥为:a95eceb1ac8c24ee28b70f7dbba912bf,示例语音文件存储路径为:/path/to/speech

下面使用PHP实现该HTTP API调用,其中getReqSigndoHttpPost可以从接口鉴权获取。

// 语音base64编码
$path   = '/path/to/speech';
$data   = file_get_contents($path);
$base64 = base64_encode($data);

// 设置请求数据
$appkey = 'a95eceb1ac8c24ee28b70f7dbba912bf';
$params = array(
    'app_id'       => '1000001',
    'format'       => '1',
    'callback_url' => 'https://ai.qq.com',
    'speech'       => $base64,
    'key_words'    => '天气',
    'time_stamp'   => strval(time()),
    'nonce_str'    => strval(rand()),
    'sign'         => '',
);
$params['sign'] = getReqSign($params, $appkey);

// 执行API调用
$url = 'https://api.ai.qq.com/fcgi-bin/aai/aai_detectkeyword';
$response = doHttpPost($url, $params);
echo $response;

上述echo $response的输出结果即API的响应结果(注意使用UTF-8编码):

{
    "ret": 0,
    "msg": "ok",
    "data": {
        "task_id": "1112_1511877399115"
    }
}

5. 回调接口描述

平台异步回调开发者上传语音时提供的callback_url,通知开发者识别结果。

6. 回调请求参数

平台将按以下参数回调开发者上传语音时提供的callback_url,请求体为JSON格式。

参数名称 是否必选 数据类型 描述
ret int 返回码(此处作为结果码); 0表示成功,非0表示出错
msg string 附加信息;ret非0时表示出错时错误原因
data object 结果数据;ret为0时有意义
+ task_id string 本次识别任务ID
+ is_end int 是否结束
+ seg_index int 识别语音片段
+ bps int 语音片段开始时间(单位毫秒)
+ eps int 语音片段结束时间(单位毫秒)
+ res object 关键词
++ key_words_size int 关键词数量
++ key_words array 关键词列表
+++ key_word string 关键词
+++ score float 可靠性得分
+++ mbtm float 当前关键词相对于该语音片段的开始时间(单位毫秒)
+++ metm float 当前关键词相对于该语音片段的结束时间(单位毫秒)

7. 回调响应参数

请开发者按照如下格式设置回调参数(JSON格式)。

参数名称 是否必选 数据类型 描述
ret int 0表示成功,非0表示出错
msg string 返回信息;ret非0时表示出错时错误原因

如果ret非0,平台会进行重试回调,最多重试两次。

8. 回调示例

使用命令行工具curl模拟平台对callback_url的请求回调。

curl -v -H "Content-Type: application/json" -X POST -d '{ "data": { "bps": 0, "eps": 2280, "is_end": 1, "res": { "key_words": [ { "key_word": "吃", "mbtm": 1, "metm": 1.24, "score": 100 } ], "key_words_size": 1 }, "seg_index": 0, "task_id": "1707_1530519895464" }, "msg": "", "ret": 0 }' callback_url
> POST ... HTTP/1.1
> Host: ...
> Content-Type: application/json
> Content-Length: 81
>
< HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8
< Transfer-Encoding: chunked
< Connection: keep-alive
< Access-Control-Allow-Origin: *
<
{
    "ret": 0,
    "msg": "ok"
}
AI开放平台公众号
关注公众号

打造升级AI项目
推送全球AI热点