AICP ASR HTTP开发手册

1. 概述

1.1 功能介绍

一句话识别 HTTP API 接口, 用于短语音的同步识别。此接口以POST方式一次性上传整个音频，识别结果将在请求响应中即刻返回，适用于对话聊天，控制命令，输入法等识别较短语音的场景。

1.2 模型特征串

AICP-10 提供的 ASR 能力接口中，模型特征串形式为：{lang}_{samplerate}_{domain}。 {lang}表示语言编码，{samplarate} 可以是 8K 或者16K，表示识别模型的训练时所用的采样率， {domain}表示领域编码。

模型特征串的概念和语言编码，请参见 《AICP 10 开发通用规范》

领域是针对识别任务的一种性能优化手段。不同领域的模型，可以对这种领域里的常见词汇、常见说话方式等进行针对性优化，就有可能得到更准确的结果。

目前常见的模型特征串如下：

模型特征串	实际应用
cn_16k_common	手机输入法，实体机器人交互，APP导航
cn_16k_huiyi	会议实时转写，录音笔离线音频转写
cn_8k_common	电话导航，电话外呼
cn_8k_zhijian	电话语音质检分析

1.3 访问认证

访问接口所需的认证机制，请参见 《AICP 10 开发通用规范》

2. 功能描述

客户端向服务端发送带有音频数据的HTTP REST POST请求，服务端返回带有识别结果的HTTP响应。

3. 请求

3.1 请求URI

POST http(s)://ip:port/v10/asr/freetalk/{property}/short_audio?appkey={appkey}

参数	类型	必选	说明
property	string	是	模型特征串，服务器端利用此值来调用不同的模型
appkey	string	是	分配给开发者的 appkey

本接口支持两种音频数据上传方式：

• JSON方式上传音频，此时包体中是一个JSON串，配置项都放在JSON串中，而音频数据也需要进行BASE64编码后放在JSON串中。
• 二进制方式上传音频，此时包体中直接放置二进制形式的音频数据，而配置项都放置在 X-AICloud-Config 头中。

两种上传方式是通过Content-Type进行区分的，当Content-Type为 application/json时，采用JSON格式上传，为application/octet-stream时，则采用二进制方式上传。

3.2 JSON格式上传

3.2.1 HTTP Header

参数	类型	必选	说明
Content-Type	string	是	application/json
X-Hci-Access-Token	string	是	从 get-access-token 接口获取的令牌

X-Hci-Access-Token 是开发者使用分配给开发者的 appkey 和 secret 访问系统服务接口 get-access-token 获取到的令牌，详细见《系统服务 HTTP 开发手册》。

3.2.2 包体

其它参数都放在包体里，以json形式提供。

参数	类型	必选	缺省	说明
config	object	是	-	识别配置信息
audio	string	是	-	要识别的语音数据，base64编码 要求base64编码后大小不超过4M，音频时长不超过1分钟。
extraInfo	string	否	空	客户端设置的信息串，服务器端只做记录，或将来作为定制版本的一些特殊信息
recordId	string	否	空	客户端设置的信息串，服务器端记录详细记录或者音频文件时会作为文件名的一部分，以便将来和客户端的信息关联。 只能包括数字、大小写字母、下划线。其它字符在作为文件名时会被转为下划线，最长64字节，超过会被截断
userId	string	否		用户Id，如果使用用户独享的热词时需要给出

注意：音频的时长限制由服务器端决定，通常为1分钟，但在私有云部署环境下可以由服务器端配置进行调整。

config 的结构如下:

参数	类型	必选	缺省	说明
profile	string	否	DEFAULT	配置集名称 缺省为 DEFAULT，表示缺省配置集
audioFormat	string	否	AUTO	音频数据格式, 取值参见下面的audioFormat 取值表格。
nbest	number	否	1	候选结果数量，可以为 1 至 10 之间的数字
outputPinyin	bool	否	false	是否输出拼音
addPunc	bool	否	false	是否加标点
digitNorm	bool	否	false	是否执行数字归一化
textSmooth	bool	否	false	是否执行文本顺滑
wordFilter	bool	否	false	是否执行敏感词过滤
wordType	string	否	DISABLED	分词类型。可以为 DISABLED (不输出分词结果), WORD (按词), CHAR (按字)
wordTpp	bool	否	false	当输出分词结果时，是输出原始结果分词信息（false） 还是输出后处理结果分词结果 (true)
vocabId	string	否	空串	识别所使用的热词Id，可以同时指定多个热词Id，以';'隔开。
vocab	string	否	空串	识别所使用的热词内容，UTF-8编码。 注意词表中的回车等特殊字符需要按照 json 规范进行转义。
senswordId	string	否	空串	识别时使用的敏感词Id，必须同时打开 wordFilter
sensword	string	否	空串	识别所使用的敏感词内容，UTF-8编码。 注意词表中的回车等特殊字符需要按照 json 规范进行转义。
olmId	string	否	空串	识别时使用的小语料优化模型Id
sa	object	否	null	是否要进行进行质检相关工作，无此项不做质检工作

audioFormat 取值：  

audioFormat	备注
auto	自动判断格式（缺省）
pcm_s16le_8k	8K signed 16bit，小端字节序, 单声道
pcm_s16le_16k	16K signed 16bit，小端字节序, 单声道
alaw_8k	8K 8bit alaw, 单声道
alaw_16k	16K 8bit alaw, 单声道
ulaw_8k	8K 8bit ulaw, 单声道
ulaw_16k	16K 8bit ulaw, 单声道
wav	wav格式，采样率、编码格式、声道由wav头决定 目前仅支持 pcm_s16le, alaw, ulaw三种编码格式，只支持单声道
ogg	ogg容器格式，支持 speex/opus 编码格式，只支持单声道

注意：

• 在audioFormat为auto时，会自动检测输入音频的格式，如果音频数据无法确定格式，会报错。
• 当设定的音频采样率、或者自动检测到的音频采样率和模型采样率不一致时，会进行自动的升采样或者降采样，但会在响应结果中输出 warning 字段。

sa 对象的结构如下：

参数	类型	必选	缺省	说明
checkEmotion	bool	否	false	是否进行情绪检测，并输出结果
checkGender	bool	否	false	是否进行性别检测，并输出结果
outputSpeed	bool	否	false	是否进行语速信息
outputVolume	bool	否	false	是否输出音量统计信息

配置集和参数:

• 配置集（profile）是在管理后台进行配置的，服务器端会使用此配置集中定义的配置作为缺省的配置参数。
• 表中各个参数的“缺省值”，表示在没有找到配置集的情况下的缺省值。此时识别会继续，但会返回 warning 信息。
• 表中各个参数的“缺省值”，也是一个配置集在初始创建时的值，但如果在管理后台中对配置集进行了更改，则会以后台更改后的作为“缺省值”。
• 如果在请求中同时定义了其它参数，则优先使用请求中带的参数

动态优化资源:

• 如果 vocabId 指定的是用户独享的热词，必须同时指定创建此热词时候的 userId，如果不是此 userId 创建的热词，此热词会被忽略，并给出 wanring 字段。
• 如果 vocabId 指定的是用户共享的热词，则 userId 被忽略；使用敏感词和小语料优化模型时，userId 也会被忽略。
• 如果 vocabId 中设置多个热词ID，这些热词必须是用户共享的热词，或者同一个 userId 创建的用户独享热词。
• 如果 vocabId 中设置多个热词ID，或者同时设置了 vocabId 和 vocab 的时候，这些热词会同时生效。
• 当 vocabId 无效或者 vocab 无效的时候，服务仍然会返回识别结果，等同于不使用热词。但此时在请求响应中会包括 warning 字段。如果同时指定了多个热词ID时，如果有一个无效，那么只会忽略掉无效的热词ID，但如果同时指定有 vocab 而 vocab 无效时，目前会导致所有热词都无效。
• 暂不支持同在 senswordId 中设置多个敏感词ID，当同时设置 senswordId 和 sensword 的时候， senswordId 优先，除非 senswordId 无效，此时会使用 sensword。
• 当 senswordId 无效或者 sensword 无效的时候，会继续识别，但会返回 warning 信息。
• 当指定了热词/敏感词用户资源的同时，在后台维护的配置集中也配置了系统资源的话，会根据配置的系统资源的处理方式决定是合并用户资源和系统资源，还是仅使用用户资源。
• 动态优化资源（热词、敏感词、小语料优化模型）的格式和规范参见 《ASR 优化指南》。
• 动态优化资源 ID 的获取方法请参见 《统一资源管理接口开发手册》。

其它：

• 如果没有设置后处理相关操作，但 wordTpp 设为 true，还是会输出原始分词结果。

3.2.3 请求示例

POST /v10/freetalk/cn_16k_common/short_audio?appkey=xxxxxx HTTP/1.1

Content-Type: application/json

X-Hci-Access-Token: xxxxxxxxxxxxxxxxxxxx

{

"config":

{

"audioFormat": "ulaw_8k",

"addPunc": true

},

"extraInfo": "abcdefg",

"audio": "/+MgxAAUeHpMAUkQAANhuRAC..."

}

3.3 二进制格式上传

3.3.1 HTTP Header

参数	类型	必选	说明
Content-Type	string	是	application/octet-stream
X-Hci-Access-Token	string	是	从 get-access-token 接口获取的令牌
X-AICloud-Config	string	是	配置参数

X-Hci-Access-Token 是开发者使用分配给开发者的 appkey 和 secret 访问系统服务接口获取到的令牌，详细见《系统服务 HTTP 开发手册》。

X-AICloud-Config 是自定义的HTTP头，格式为逗号隔开的键值对，例如 name1=value1,name2=value2。允许的键如下：

参数	类型	必选	缺省
extraInfo	string	否	空
recordId	string	否	空
userId	string	否	空
profile	string	否	空
audioFormat	string	否	AUTO
nbest	number	否	1
outputPinyin	bool	否	false
addPunc	bool	否	false
digitNorm	bool	否	false
textSmooth	bool	否	false
wordFilter	bool	否	false
wordType	string	否	DISABLED
wordTpp	bool	否	false
vocabId	string	否	空
senswordId	string	否	空
olmId	string	否	空
sa.checkEmotion	bool	否	false
sa.checkGender	bool	否	false
sa.outputSpeed	bool	否	false
sa.outputVolume	bool	否	false

各参数含义请参见JSON上传方式时候的参数列表。

注意：

• 在使用二进制格式上传的情况下，不支持直接上传热词或敏感词内容，只能上传热词ID、敏感词ID。
• 当所有参数都使用默认配置时，也必须有 X-AICloud-Config头，值为空串。

3.3.2 包体

在二进制格式上传方式下，包体中直接放置二进制的音频流，无需进行 BASE64 编码。包体大小不超过4M，音频时长不超过1分钟。

3.3.3 请求示例

POST /v10/freetalk/cn_16k_common/short_audio?appkey=xxxxxx HTTP/1.1

Content-Type: application/octet-stream

X-Hci-Access-Token: xxxxxxxxxxxxxxxxxxxx

X-AICloud-Config: audioFormat=ulaw_8k,addPunc=true,extraInfo=abcdefg

二进制音频数据...

4. 响应

发送识别的HTTP请求之后，会收到服务端的响应，识别的结果以JSON字符串的形式保存在该响应中。无论是JSON方式上传还是二进制方式上传音频数据，结果响应都是一样的。

请求是否成功通过HTTP 状态码来区分。

4.1 成功响应

当 HTTP 状态码为 200 时，表示请求成功，识别结果在包体中。

4.1.1 响应字段说明

参数	类型	说明
traceToken	string	服务内部的 token 字符串，可用于日志追溯。
result	object	调用成功表示识别结果，调用失败时将没有此字段, 多候选输出时，这里是第一候选结果
alternatives	array	多候选时，如果除了第一候选结果外还有其它候选结果则有此字段，不包括第一候选结果。 如果不要求多候选结果或者识别候选结果只有1个时，没有此字段
analysis	object	当输入配置中sa不为空时会输出此字段，否则无此字段
warning	array	调用成功时，可能有的警告信息

result 的结构如下：

参数	类型	说明
text	string	识别出的文本内容
pinyin	string	对应的拼音，当 outputPinyin 设为 false 时，没有此项
confidence	number	识别的置信度, 介于 [0.0-1.0] 之间。 注意，目前置信度不是很准确，不要过多依赖此值
words	array	分词信息。 可选，如果客户端发送的 wordType 配置为 DISABLED，那么将没有此项

alternatives 中的每个元素是一个 json object, 其结构和 result 一致。

words 中的每个元素是一个 json object，其结构如下：

参数	类型	说明
st	number	分词在音频流中的开始时间偏移，单位: ms
et	number	分词在音频流中的结束时间偏移，单位: ms
w	string	分词对应的文本
py	string	分词对应的拼音，当 outputPinyin设为 false 时，没有此项
c	number	置信度
t	string	分词的类别，详见分词类别说明

分词类别说明：

类型	全名	说明
U	Userword	用户热词
P	Punctuation	标点
S	Smoothed	顺滑词
M	Masked	被过滤的敏感词
D	DigitNorm	数字归一化词

为节省传输的内容，这里的参数、分词类型都用比较简单的词汇替代。有可能会是多个字符，例如UM，表示既是用户热词又是敏感词。当是正常词没有任何特殊分词标识时，t 项被省略。

如果单元类型为标点符号，其st, et 值相同。目前打标点功能对中文识别只会增加"，"、"。"、"？"三种，其st, et值一定与和前一单元的et相同。如果将来会增加其它标点符号，如果是左引号、左书名号之类，其st,et 会与下一单元的st相同。

由于存在文本后处理的操作，例如打标点、数字归一化等，因此可以选择输出原始识别结果的分词信息还是后处理结果的分词信息。当输出原始识别结果时，分词结果是和原始音节一一对应的，也不会出现上述后处理相关的分词类型属性（ P, S, M, D），但可能会有 U 类型。当输出后处理结果的分词信息时，则会增加标点单元、显示数字归一化后的单元、会标识后处理的分词类型属性等。

如果输出的是后处理分词信息，则会出现如下示例情况：

• “百分之十二”，分词输出的单元内容为“百分之”、“十二”，但整句的输出为"12%"。
• “嗯我们开始吧”，分词输出的单元内容为“嗯”(顺滑词）、“我们”、“开始”、“吧”，但整句的输出为"我们开始吧"。
• “这个是法轮功的视频”，分词输出的单元内容为“这个”、“是”、“法轮功”(敏感词)、“的”、“视频”，但整句的输出为"这个是***的视频"。

analysis 对象为质检相关的信息，其结构如下：

参数	类型	说明
emotions	array	情绪信息数组，如果 checkEmotion 为 false 或者没有检测到情绪信息时，没有此字段
gender	object	性别信息，如果 checkGener 为false，没有此字段
speed	number	语速，如果 outputSpeed 为 false, 则无此字段
avgVol	number	平均音量，如果 outputVolume 为 false, 则无此字段
maxVol	number	最大音量，如果 outputVolume 为 false, 则无此字段

emotions 的每一个元素是一个json object, 其结构如下：

参数	类型	说明
st	number	音频开始时间，单位ms
et	number	音频结束时间，单位ms
c	number	置信度，范围[0.0, 1.0]
e	string	情绪， HAPPY, ANGRY, SAD, DISGUSTED 之一

gender 对象为性别信息，其结构如下：

参数	类型	说明
c	number	置信度，范围[0.0, 1.0]
g	string	性别，FEMALE, MALE 之一

注意：

• 目前版本中，一个分句中进行情绪检测时最多也只会检出一个结果，因此要么没有 emotions 字段，要么 emotions 数组元素个数为1
• 如果设置了 checkEmotion, 但没有检测到情绪信息时，结果中也不会输出 emotions 项
• 目前版本中，情绪检测也只能检出 ANGRY 类。
• 如果 sa 配置不为空，但 analysis 中不需要任何输出项时（或者是 sa 之下配置的均为 false，或者即使配置了情绪检测，也没有检测出情绪），输出为 {}

warning 是一个数组，每一项的结构如下：

参数	类型	必选	说明
code	number	是	警告代码，具体的警告错误码见后
message	string	是	警告的详细信息

warning 字段说明有正常流程之外的情况发生，但可以继续识别下去。其 code 包括：

code	说明
100	输入引擎的采样率和模型的采样率不一致，自动进行了升采样或降采样
101	vocabId 对应的热词找不到，或者无效
102	vocab 的热词内容非法或者无效
103	senswordId 对应的热词找不到，或者无效
104	sensword 的热词内容非法或者无效

4.1.2 正常响应示例

普通结果示例：

{

"traceToken": "token_abcd_12345",

"result":

{

"text": "欢迎使用语音云服务。",

"confidence": 0.9

}

}

多候选示例：

{

"traceToken": "token_abcd_12345",

"result":

{

"text": "欢迎使用语音云服务。",

"confidence": 0.9

}

"alternatives":

[

{

"text": "欢迎试用语音云服务。",

"confidence": 0.8

}

]

}

带质检结果示例：

{

"traceToken": "token_abcd_12345",

"result":

{

"text": "欢迎使用语音云服务。",

"confidence": 0.9

}

"analysis":

{

"speed": 5.46,

"avgVol": 0.035,

"maxVol": 0.188,

"emotions":

[

{

"st": 100,

"et": 1500,

"c": 0.3,

"e": "ANGRY"

}

],

"gender":

{

"c": 0.89,

"g": "FEMALE"

}

}

}

分词结果示例：

{

"traceToken": "token_abcd_12345",

"result":

{

"text": "欢迎使用语音云服务。",

"confidence": 0.9

"words":

[

{

"st": 400,

"et": 1000,

"w": "欢迎",

"c": 0.82,

},

{

"st": 1000,

"et": 1450,

"w": "使用",

"c": 0.33,

},

{

"st": 1450,

"et": 2000,

"w": "语音云",

"c": 0.33,

},

{

"st": 2000,

"et": 2450,

"w": "服务",

"c": 0.33,

},

{

"st": 2450,

"et": 2450,

"w": "。",

"c": 0.0,

"t": "P"

},

]

}

}

带警告的结果示例：

{

"traceToken": "token_abcd_12345",

"result":

{

"text": "欢迎使用语音云服务。",

"confidence": 0.9

}

"warning":

[

{

"code": 100,

"message": "speech sample rate automatically changed from 44100 to 16000"

},

{

"code": 101,

"message": "vocabId xxxxx not found"

}

]

}

4.2 失败响应

如果HTTP 状态码不为 200 时，表示请求失败。

4.2.1 响应字段说明

参数	类型	说明
traceToken	string	服务内部的 token 字符串，可用于日志追溯。 在某些错误情况下可能没有此令牌字符串。
error	object	错误信息

error 的结构如下：

参数	类型	说明
code	number	错误码，请参见 《AICP 10 开发通用规范》
message	string	详细的错误信息

4.2.2 失败响应示例

{

"error":

{

"code": 3,

"message": "10004: Parse Task Config Failed",

}

}

5. 版本记录

接口版本	平台支持版本	组件及支持版本	修改内容
10.4.0	10D.1	aicp_asr_ft 10.8.0	1. 新增小语料优化模型设置功能 (olmId) 2. 新增 userId 参数 3. 新增配置集参数(profile)
10.3.0	10C.0	aicp_asr_ft 10.5.0	1. 新增敏感词设置功能 2. 新增质检功能（增加 sa 及其下字段）
10.2.0	10B.0	aicp_asr_ft 10.2.0	1. 新增 recordId 字段 2. 新增输出拼音、文本后处理相关字段 3. 支持多热词
10.1.0	10A.1	aicp_asr_ft 10.1.0	1. 新增热词设置功能（增加 vocab 和 vocabId 字段） 2. 新增 warning 输出字段
10.0.0	10A.0	aicp_asr_ft 10.0.0	初始版本