AIWIFI绘本接入
概述
本文档是关于绘本接入的一些相关说明，开发者需要按照本说明文档进行来使用提供的功能。
接口具体说明
接口地址
接口地址1： http://smartdevice.ai.turingapi.com/speech/chat
接口地址2：
http接入： http://iot.turingos.cn/mmui/picbook
https接入： https://iot.turingos.cn/mmui/picbook
若对数据通信有较高的安全要求，建议选择https接入方式来访问图灵服务，由于ssl层验证预计会额外多花费40~50ms。
说明：
1. 接口地址2，智能dns解析+全站加速，最大程度加速绘本全链路的云端响应时间，只支持开通了绘本功能的apikey使用。
2. 接口地址1的地址依旧可以正常使用。
请求方法
method: POST
content-type: multipart/form-data
请求参数
| 参数 | 类型 | 必选 | 说明 |
|---|---|---|---|
| parameters | json | 是 | 参考parameters字段说明 |
| speech | 二进制流文件 | 是 | jpg格式的图片(分辨率见图片分辨率详解部分) |
parameters字段说明
| 参数 | 类型 | 必选 | 说明 |
|---|---|---|---|
| ak | String | 是 | apikey，图灵官网申请 |
| uid | String | 是 | 设备ID加密后的字符串,加密方式见AI-WIFI 接入文档 |
| token | String | 是 | 请求令牌，初次请求可为空，请求会返回token值，开发者自己保存起来，用于下一次请求，详情见AI-WIFI接入文档中Token更新机制 |
| flag | int | 否 | flag=0：不输出文本（默认） flag=2：输出tts文本信息 |
| type | int | 是 | type=4,表示绘本（固定值) |
| extra | json | 是 | 参见extra字段说明 |
extra字段说明
| 参数 | 类型 | 必选 | 说明 |
|---|---|---|---|
| imgFlagId | String | 是 | 请求的标记，方便查询日志排查问题，32位（由小写字母和数字组成） |
| cameraId | int | 是 | 摄像头标定后由图灵生成并提供 |
| bookId | long | 否 | 当前阅读绘本的id，初次请求时不需要此字段，图灵识别到封面后会回传此id值，设备端需记录此id并在后续请求中都带上该id值，当更换书本时，此时重新识别到新的封面，图灵会返回新书的id值，此时需要将之前记录的id替换掉 |
| innerUrlFlag | int | 否 | 是否需要内页的音频URL链接（pageUrl）: innerUrlFlag = 0:表示不需要(默认) innerUrlFlag = 1:表示需要 |
| debug | int | 否 | 是否开启调试模式：机器人(apikey)正式量产后(机器人状态变成正式状态)，不支持开启调试 debug=0:不开启调试 debug=1:开启调试 |
| typeFlag | int | 是 | typeFlag=1：标准版绘本机器人 typeFlag=3：标准版绘本台灯 typeFlag=4：升级版绘本机器人 typeFlag=5：升级版绘本台灯 typeFlag=6：指读版绘本机器人 typeFlag=7：指读版绘本台灯 typeFlag=10：纯指读版绘本机器人 typeFlag=11：纯指读版绘本台灯 |
| accessModel | int | 否 | 访问公有库还是私有库,默认1： accessModel=1：公有库+私有库 accessModel=2：公有库 accessModel=3：私有库 |
| modelOrder | int | 否 | 优先级顺序,默认2： modelOrder=1：公有库优先 modelOrder=2：私有库优先 |
| languageOrder | int | 否 | 不建议上传，以家长端配置的为主 languageOrder=1：中文优先（默认） languageOrder=2：英文优先 |
| textFlag | int | 否 | 是否返回热区文本,默认0(需要联系图灵商务或者项目进行开通): textFlag=0：不返回 textFlag=1：返回热区文本 |
| osState | String | 否 | 清除休眠状态： 1. 固定传"clean" 2. 非休眠状态不可使用，否则返回1009的operateState码 |
返回参数
| 参数 | 类型 | 说明 |
|---|---|---|
| token | String | 请求令牌，开发者自己保存起来，用于下一次请求 |
| tts | String | 语义解析文本结果。当flag=2时，会返回此参数值（绘本内页请求时没有此字段输出） |
| code | int | 返回码 2xxxx 功能码，可以参考附件-功能码(20039表示绘本) 4xxxx 错误码，可以参考附件-错误码 |
| emotion | int | 情绪ID返回数据，可以参考附件-情绪ID |
| func | json | 参见func字段说明 |
func字段说明
| 参数 | 类型 | 说明 |
|---|---|---|
| intentCode | int | 绘本状态，参考IntentCode字段说明 |
| msg | string | 返回信息（英文） |
| commandUrl | string | 提示语音频信息 |
| titleData | TitleData | 封面识别返回信息，参考TitleData字段说明 |
| innerData | InnerData | 内页识别返回信息, 参考InnerData字段说明 |
| hotZone | HotZoneData | 点读热区返回信息, 参考HotZoneData字段说明 |
| ext | ExtData | 扩展字段,参考ExtData字段说明(需要联系图灵商务或者项目进行开通) |
| debugData | DebugData | 调试信息，参考DebugData字段说明（需要开启调试模式，即debug=1时，才有此返回信息） |
| funcData | FuncData | 功能参数,支持OCR和指读结果,参考FuncData字段说明 |
| picbookVoiceExtraUrl | 数组 | 当operateState=3000或4000或3100或4100时有效 |
| operateState | int | 参考operateState码 |
| bookSign | String | 绘本标识 |
TitleData 字段说明
| 参数 | 类型 | 说明 |
|---|---|---|
| bookId | long | 绘本Id |
| name | String | 绘本名称 |
| author | String | 绘本作者名称 |
| publisher | String | 出版社名称 |
| cover | String | 封面图片的url |
| zipUrl | String | 绘本压缩包的url |
| bookVersion | int | 绘本版本，判断是否需要更新 |
| nameUrl | String | 绘本名称音频文件的url |
| bookName | String | 绘本模型标识（无需关注） |
InnerData字段说明
| 参数 | 类型 | 说明 |
|---|---|---|
| bookId | long | 绘本Id |
| pageNum | int | 绘本页数 |
| url | String | 绘本内页音频 |
| pageUrl | String | 绘本内页音频 |
DebugData字段说明
| 参数 | 类型 | 说明 |
|---|---|---|
| imgOriginalUrl | String | 原图片链接 |
| imgProcessedUrl | String | 算法处理后的图片链接 |
HotZoneData字段说明
| 字段名称 | 类型 | 是否必须 | 介绍 |
|---|---|---|---|
| pieceIndex | int | Y | 热区索引 |
| pieceUrl | String | Y | 热区音频文件URL或音频ID |
| pieceContent | String | N | 热区文本 |
| transContent | String | N | 热区英文翻译为中文的文本 |
ExtData字段说明
| 字段名称 | 类型 | 是否必须 | 介绍 |
|---|---|---|---|
| bookEvalFlag | boolean | N | 是否支持口语评测（需要后台开启输出口语评测标志位权限，封面识别时输出） bookEvalFlag=true：该书支持口语评测 bookEvalFlag=false：该书不支持口语评测 |
| evalFlag | int | N | 是否支持口语评测（需要后台开启输出口语评测标志位权限，内页识别时输出） evalFlag=1：支持口语评测 evalFlag=0：不支持口语评测 |
| multiAudios | Array[json] | N | 自定义热区多音频，参考MultiAudio字段说明 |
FuncData字段说明
| 参数 | 类型 | 说明 |
|---|---|---|
| ocr | int | ocr=0,表示普通识别 ocr=1,表示ocr（后续需要上传640x480的图片） |
| finger | int | finger=0,表示无指读 finger=1,表示有指读 |
MultiAudio字段说明
| 参数 | 类型 | 说明 |
|---|---|---|
| text | String | 热区文本 |
| url | String | 热区音频文件URL或音频ID: URL有效时间为10分钟（自己上传的URL除外） |
| textKey | String | 音频名称 textKey=0：中文 textKey=1：英文 textKey=2：粤语 textKey=3：讲解 textKey=4：视频 |
operateState码
| 值 | 说明 |
|---|---|
| 1001 | 绘本图片识别异常，有intentCode |
| 1005 | 图片内容大小非法(取值范围:[1,80]kb) |
| 1006 | 图片内容处理异常 |
| 1007 | 请求typeFlag非法；比如该APIKEY不支持typeFlag=4，但是请求的时候使用该typeFlag |
| 1008 | 请求中无图片信息 |
| 1009 | 错误输入(非法使用唤醒功能) |
| 1200 | 休眠状态 |
| 2000 | 绘本识别正常 |
| 3000 | 正常，有附加内容输出，开启文本输入; 附件文本在字段picbookVoiceExtraUrl |
| 3100 | 正常，有附加内容输出，关闭文本输入; 附件文本在字段picbookVoiceExtraUrl |
| 4000 | 正常，有附加内容输出（注意音频类型），开启文本输入; 附件文本在字段picbookVoiceExtraUrl |
| 4100 | 正常，有附加内容输出，关闭音频输入; 附件文本在字段picbookVoiceExtraUrl |
IntentCode码
| 值 | 说明 |
|---|---|
| 200 | 识别绘本封面成功 |
| 201 | 识别绘本内页成功 |
| 202 | 绘本扉页识别成功 |
| 203 | 绘本无文本内页识别成功 |
| 204 | 绘本无意义内页识别成功 |
| 205 | 封面识别成功，热区识别成功(预留code：因封面暂无热区，暂未使用) |
| 206 | 封面识别成功，热区识别失败(预留code：因封面暂无热区，暂未使用) |
| 207 | 内页识别成功，热区识别成功 |
| 208 | 内页识别成功，热区识别失败 |
| 300 | 绘本封面识别失败 |
| 301 | 绘本内页识别失败 |
| 302 | 非缺省参数未找到 |
| 303 | 摄像头ID信息未找到 |
| 304 | 图片无法打开 |
| 305 | 图片尺寸异常 |
| 306 | 绘本内容未录入 |
| 307 | 当前绘本页音频缺失 |
| 308 | 未开通OCR功能 |
| 309 | 未开通指读功能 |
| 310 | 暂不支持该功能；比如本书需要使用OCR识别，但当前typeFlag为非OCR版本 |
| 311 | 此绘本为私有绘本 |
| 312 | 非法bookId |
| 313 | 此书不支持指读 |
| 314 | 不支持此资源类型 |
| 400 | 封面算法识别超时 |
| 401 | 内页算法识别超时 |
| 402 | 绘本算法未知异常 |
| 501 | 没有开通绘本功能，调用次数超过限制，没有进入绘本，调用或者请求其他服务器异常等 |
示例
请求参数
POST /speech HTTP/1.1
Host: smartdevice.ai.turingapi.com
Connection: keep-alive
Content-Length: 26899
Cache-Control: no-cache
Content-Type: multipart/form-data;boundary=----WebKitFormBoundarybtXd96AztrPD9eZT
Accept: */*
Accept-Encoding: gzip, deflate
Accept-Language: zh-CN
------WebKitFormBoundarybtXd96AztrPD9eZT Content-Disposition: form-data;name="parameters"
{
"ak":"***",
"extra": {
"bookId": 250,
"cameraId": ***,
"innerUrlFlag": 1,
"debug": 0,
"typeFlag": 1
},
"flag": 2,
"token":"1565d0da6c2842f9a863748b5863dcd5",
"type": 4,
"uid":"***"
}
------WebKitFormBoundarybtXd96AztrPD9eZT
Content-Disposition: form-data;name="speech"filename="pcm_8K_16bit_test.pcm"
Content-Type: application/octet-stream
二进制文件内容区
------WebKitFormBoundarybtXd96AztrPD9eZT--
返回结果
{
"code": 20039,
"emotion": 0,
"func": {
"intentCode": 200,
"operateState": 2000,
"titleData": {
"bookId": 2160,
"bookName": "187148b529c147a298c160ae71f2a6d2",
"bookVersion": 7,
"name": "鲸鱼",
"zipUrl": "http://universe-file-limit.turingapi.com/201904022105/7bce79ac310ddab45926eb8759******/robot_story/2160/2160.zip"
}
},
"token": "1565d0da6c2842f9a863748b5863dcd5"
}
附录
功能码
| 功能码 | 功能 | 说明 |
|---|---|---|
| 20039 | 绘本 | 使用绘本功能 |
错误码
| 错误代码 | 返回msg | 详细描述 |
|---|---|---|
| 40001 | value error | 字段错误 |
| 40002 | illegal value | 非法字段 |
| 40003 | value is null or missing | 字段为空或错误 |
| 40004 | asr failure | 语音解析失败 |
| 40005 | tts failure | 文本转语音失败 |
| 40006 | nlp failure | 语义解析失败 |
| 40007 | token invalid value | 无效token |
| 40008 | is expired | 过期 |
| 40010 | active interaction corpus not exist | 主动交互语料不存在 |
| 40011 | greeting corpus not exist | 打招呼语料不存在 |
| 40012 | request is forbidden | 拒绝请求 |
| 40013 | out of device count limit | 请求超出限制 |
| 49999 | unknown error | 未知错误 |
| 40000 | in progress | 正在进行流式识别 |
| 42000 | synthetic tts text is null | 合成tts的文本为null |
| 47340 | no picture book permission | 没有绘本权限（使用正式环境2地址时) |
绘本休眠说明
- 2020年7月2日起申请的apiKey绘本技能默认开启休眠功能！如果需要关闭，请联系图灵项目同事。
- 连续30次绘本识别失败或识别结果相同，则进入休眠状态。
- 设备处于休眠状态时(operateState=1200)，此时图灵云端返回信息中会告知休眠状态和提醒距离下次自动唤醒的时间。
- 设备处于休眠状态时(operateState=1200)，可传参osState=clean删除休眠状态，但如果不在休眠状态中传该参数，则为非法传参，输出状态(operateState=1009)与提示语。
- 在设备自动唤醒后，请求结果5次和进入休眠状态一样的时候，则会再次加深睡眠，若5次请求出现一次别的数据则会重新计数。
设备处于休眠状态时，请求返回示例，其中sleepSec为休眠的时间（单位为秒）：
{
"code": 20039,
"tts": "休眠中，请9秒后再试试吧。",
"nlp": [
"http://turing-iot.oss-cn-beijing.aliyuncs.com/tts/tts-a31a2202e9f******85a63a45125821a-3278a2e951354144a493c074ecae88ec.mp3"
],
"token": "f18fe154364a462488bcc690f1e1fe87",
"func": {
"sleepSec": 9,
"operateState": 1200
},
"emotion": 0
}
常见问题&解决方案
-
当封面、扉页、内页重复识别时（返回信息相同)，不打断播放、不重复播放。
-
当返回的非封面、扉页、内页识别code时，根据code做相应的处理。
-
当光线发生变化，比如有人遮挡光线，影子印在书上也会导致识别为翻页，这个怎么处理？ 翻页检测是检测像素变化的,所以有影子,认为也是翻页,这个时候在本地记录bookid和pageNum，如果这次请求回复的结果还是同一页，只播放一次下发的url，不重复播放音频，直到识别结果不同为止。
-
绘本识别的开始即为封面识别，所有绘本的读取都需要先进行封面识别，所以进入绘本技能时需要播放提示语引导用户去先识别封面，产品说明上也要着重强调这一点。当进行封面识别时，识别结果会受书本的摆放情况而定，需要尽量摆放方正。当封面识别错误时，会返回错误码，多次错误可以前端进行语音提示。
-
当需要进行图片debug调试时，可以选择在请求参数中extra下的debug参数设为1，则进入调试模式，返回参数会增加debugDate的数据返回【imgOriginalUrl（原图片链接）和imgProcessedUrl（算法处理后的图片链接）】，可通过对原图片和处理后的图片进行来进行参数的调整。
-
针对云端的中英文绘本，由于封面相同，仅文字不同（封面识别过程中无OCR辅助），目前推荐的模式如下：
-
通过AIWIFI请求图灵绘本时，建议不上传languageOrder字段，此时默认优先阅读中文版本；
-
在上述情况的背景下，家长可以通过绘本小程序，设置中英文优先，此时云端会以家长端的配置为主（默认为中文版本）；
-
在上述情况的背景下，孩子可以通过设备的按键，进行中英文的切换，此时云端会以某次请求为主，通过配置选择对应的中英文版本。
因此，若在固件上，默认选择languageOrder=中文，那么此时家长端配置消失。
-