场景识别 API 文档
#接口说明
场景识别,可以精准识别自然环境下数十种场景,让智能相册管理、照片检索和分类,等基于场景的应用展现得更加直观。该能力是通过HTTP API的方式给开发者提供一个通用的接口,适用于一次性交互数据传输的AI服务场景,块式传输。相较于SDK,API具有轻量、跨语言的特点,不过请注意该接口使用的HTTP API协议不支持跨域。
#接口Demo
示例demo请点击 这里 下载。
目前仅提供部分开发语言的demo,其他语言请参照下方接口文档进行开发。
也欢迎热心的开发者到 讯飞开放平台社区 分享你们的demo。
接口请求参数
#请求头
在 Http Request Header 中配置以下参数。#授权认证
以下参数用于授权认证:| 参数 | 格式 | 说明 | 必须 |
|---|---|---|---|
| X-Appid | string | 讯飞开放平台注册申请应用的应用ID(appid) | 是 |
| X-CurTime | string | 当前UTC时间戳 从1970年1月1日0点0 分0 秒开始到现在的秒数 | 是 |
| X-Param | string | 相关参数JSON串经Base64编码后的字符串,详见业务参数 | 是 |
| X-CheckSum | string | 令牌,计算方法:MD5(APIKey + X-CurTime + X-Param),三个值拼接的字符串,进行MD5哈希计算(32位小写) | 是 |
注:
- APIKey:接口密钥,在讯飞开放平台控制台添加相应服务后即可获取,调用方注意保管,如泄露,可到控制台提交工单联系技术人员重置;
- X-CheckSum 有效期:出于安全性考虑,每个 X-CheckSum 的有效期为 5 分钟(用 X-CurTime 计算),同时 X-CurTime 要与标准时间同步,否则时间相差太大,服务端会直接认为 X-CurTime 无效;
- BASE64 编码采用 MIME 格式,字符包括大小写字母各26个,加上10个数字,和加号 + ,斜杠 / ,一共64个字符。
X-CheckSum 生成示例:
String APIKey="abcd1234";String X-CurTime="1502607694";String X-Param="eyAiYXVmIjogImF1ZGlvL0wxNjtyYXR...";String X-CheckSum=MD5(apiKey + X-CurTime + X-Param);
#业务参数
X-Param 为各配置参数组成的 JSON 串经 BASE64 编码之后的字符串,原始 JSON 串各字段说明如下:| 参数 | 类型 | 必填 | 说明 | 备注 |
|---|---|---|---|---|
| image_url | string | 否 | 图片下载链接 | 采用请求头设置image_url参数传入图片时填此参数 |
| image_name | string | 是 | 图片名称 | image_url方式和Body传图片方式都需要设置图片名称,例如:img.jpg |
注意:图片数据可以通过两种方式上传,第一种在请求头设置image_url参数,第二种将图片二进制数据写入请求体中。若同时设置,以第一种为准。
X-Param生成示例:
原始JSON串:{"image_name": "img.jpg","image_url":""}BASE64编码(即X-Param):eyJlbmdpbmVfdHlwZSI6InNtczE2ayIsImF1ZSI6InJhdyJ9
#请求体
以POST表单的形式提交以下参数: 将图片的二进制数据写入 Http Request Body 中#接口返回参数
返回值为 json 串,各字段如下:| JSON字段 | 类型 | 说明 |
|---|---|---|
| code | string | 结果码(具体见SDK&API错误码查询 ) |
| data | array | 识别结果 |
| desc | string | 错误描述,会话成功为success |
| sid | string | 会话ID,用来唯一标识本次会话,如会话报错无法解决,可以通过工单 提供 sid 给讯飞技术人员分析解决。 |
| JSON字段 | 类型 | 说明 |
|---|---|---|
| label | number | 大于等于0时,表明图片属于哪个分类或结果;等于-1时,代表该图片文件有错误,或者格式不支持(gif图不支持) |
| labels | array | 表示前5个最可能场景的label |
| rate | string | 介于0-1间的浮点数,表示该图像被识别为某个分类的概率值,概率越高、机器越肯定 |
| rates | array | 和labels对应,前5个最可能场景对应得分 |
| name | string | 图片的url地址或名称 |
| review | bool | 本次识别结果是否存在偏差,返回true时存在偏差,可信度较低,返回false时可信度较高,具体可参考rate参数值 |
| tag | string | 图片标签,值为Local Image或Using Buffer(无实际意义) |
调用示例
注: demo只是一个简单的调用示例,不适合直接放在复杂多变的生产环境使用
#常见问题
#场景识别的主要功能是什么?
答:精准识别自然环境下数十种场景,让智能相册管理、照片检索和分类等,基于场景的应用展现得更加直观。#场景的类别有哪些?
答:对实际应用场景分为室内、室外、自然风景和其他四大分类,每个分类都会按照实际场景细分为多个类别。#场景识别支持什么应用平台?
答:目前场景识别支持Web api应用平台。#场景识别如何试用?
答:可以的,登录讯飞开放平台—-控制台—-我的应用(没有应用先创建一个应用)—-图像识别—-场景识别(可免费调用Webapi接口共500次服务量,授权期限1个月) # 物体识别 API 文档 ## #接口说明 物体识别,采用通用物体检测算法,有效检测图像中的动物、交通工具、生活家具等2万多种生活常见物体。该能力是通过HTTP API的方式给开发者提供一个通用的接口,适用于一次性交互数据传输的AI服务场景,块式传输。相较于SDK,API具有轻量、跨语言的特点,不过请注意该接口使用的HTTP API协议不支持跨域。
#接口Demo
示例demo请点击 这里 下载。
目前仅提供部分开发语言的demo,其他语言请参照下方接口文档进行开发。
也欢迎热心的开发者到 讯飞开放平台社区 分享你们的demo。
#接口要求
| JSON字段 | 类型 | 说明 |
|---|---|---|
| code | string | 结果码(具体见SDK&API错误码查询 ) |
| data | array | 识别结果 |
| desc | string | 错误描述,会话成功为success |
| sid | string | 会话ID,用来唯一标识本次会话,如会话报错无法解决,可以通过工单 提供 sid 给讯飞技术人员分析解决。 |
| JSON字段 | 类型 | 说明 |
|---|---|---|
| label | number | 大于等于0时,表明图片属于哪个分类或结果;等于-1时,代表该图片文件有错误,或者格式不支持(gif图不支持) |
| labels | array | 表示前5个最可能类别的label |
| rate | string | 介于0-1间的浮点数,表示该图像被识别为某个分类的概率值,概率越高、机器越肯定 |
| rates | array | 和labels对应,前5个最可能类别对应得分 |
| name | string | 图片的url地址或名称 |
| review | bool | 本次识别结果是否存在偏差,返回true时存在偏差,可信度较低,返回false时可信度较高,具体可参考rate参数值 |
| tag | string | 图片标签,值为Local Image或Using Buffer(无实际意义) |
成功结果:
{"code":"10106","data":[],"desc":"invalid parameter|invalid X-Param","sid":"tup00000001@ch239c0ef594db6a6b00"}
{"code":"0","data":[{"label":19015,"labels":[19015,18927,18929,698,5588],"name":"img.jpg","rate":0.10702908039093018,"rates":[0.10702908039093018,0.08567219227552414,0.0592394582927227,0.04257886856794357,0.04108942672610283],"review":true,"tag":"Local Image"}],"desc":"success","sid":"tup00000005@ch2ee40efd592d6a6b00"}
#调用示例
注: demo只是一个简单的调用示例,不适合直接放在复杂多变的生产环境使用
#常见问题
#物体识别的主要功能是什么?
答:采用通用物体检测算法,有效检测图像中的动物、交通工具、生活家具等2万多种生活常见物体。 #### #识别的物体有哪些? 答:识别的内容包括动物、交通工具、生活家具等2万多种生活常见物体,详细内容可查看接口文档。#物体识别支持什么应用平台?
答:目前场景识别支持Web api应用平台。#物体识别如何试用?
答:可以的,登录讯飞开放平台—-控制台—-我的应用(没有应用先创建一个应用)—-图像识别—-场景识别(可免费调用Webapi接口共500次服务量,授权期限1个月)#物体识别的图片要求?
答:图片格式为.png、.jpg、.jpeg、.bmp、.tif。图片大小不超过800k。 # 场所识别 API 文档 ## #接口说明 场所识别,支持识别80多类通用场所,包括会议室、广场、航站楼等。支持返回结果的结构化数据,调用简单,只需上传单张图片,秒级别获取识别结果。广泛应用于拍照识图、幼教科普、图片分类等场景。 该能力是通过HTTP API的方式给开发者提供一个通用的接口,适用于一次性交互数据传输的AI服务场景,块式传输。相较于SDK,API具有轻量、跨语言的特点,不过请注意该接口使用的HTTP API协议不支持跨域。#接口Demo
示例demo请点击 这里 下载。
目前仅提供部分开发语言的demo,其他语言请参照下方接口文档进行开发。
也欢迎热心的开发者到 讯飞开放平台社区 分享你们的demo。
#接口要求
请求参数
在调用业务接口时,都需要在 Http Request Body 中配置以下参数,请求数据均为json字符串。| 参数名 | 类型 | 必传 | 描述 |
|---|---|---|---|
| header | object | 是 | 协议头部,用于上传平台参数 |
| header.app_id | string | 是 | 在平台申请的appid信息 |
| header.status | string | 是 | 请求状态,取值范围为:3(一次传完) |
| parameter | object | 是 | 能力参数,用于上传服务特性参数 |
| parameter.s5833e7f6 | object | 是 | 用于上传功能参数 |
| parameter.s5833e7f6.func | string | 是 | 子功能选择(image/place:场所识别) |
| parameter.s5833e7f6.result | object | 是 | 用于上传响应数据参数 |
| parameter.s5833e7f6.result.encoding | string | 否 | 文本编码,可选值:utf8(默认值) |
| parameter.s5833e7f6.result.compress | string | 否 | 文本压缩格式,可选值:raw(默认值) |
| parameter.s5833e7f6.result.format | string | 否 | 文本格式,可选值:json(默认值) |
| payload | object | 是 | 用于上传请求数据 |
| payload.data1 | object | 是 | 用于上传第一张图像数据 |
| payload.data1.encoding | string | 否 | 第一张图像编码 可选值: jpg:jpg格式(默认值) jpeg:jpeg格式 png:png格式 bmp:bmp格式 |
| payload.data1.image | string | 是 | 第一张图像数据,base64编码,需保证图像文件大小base64编码后不超过4MB |
| payload.data1.status | int | 否 | 第一张数据状态,取值范围为:3(一次传完) |
{"header": {"app_id": "XXXXXXXX","status": 3},"parameter": {"s5833e7f6": {"func": "image/place","result": {"encoding": "utf8","compress": "raw","format": "json"}}},"payload": {"data1": {"encoding": "jpg","status": 3,"image": "/4AAQSkZJRgA..."},}}
#返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| header | object | 协议头部,用于描述平台特性的参数 |
| header.sid | string | 本次会话id |
| header.code | int | 返回码 0表示会话调用成功(并不一定表示服务调用成功,服务是否调用成功以text字段中的ret为准) 其它表示会话调用异常,详情请参考错误码 。 |
| header.message | string | 描述信息 |
| payload | object | 数据段,用于携带响应的数据 |
| payload.result | object | 场所识别响应数据块 |
| payload.result.compress | string | 文本压缩格式,仅在设置了parameter.s5833e7f6.result.compress参数时返回 |
| payload.result.encoding | string | 文本编码,仅在设置了parameter.s5833e7f6.result.encoding参数时返回 |
| payload.result.format | string | 文本格式,仅在设置了parameter.s5833e7f6.result.format参数时返回 |
| payload.result.text | string | 场所识别返回结果,需要对其进行base64解码,解码后的返回字段如下 |
payload.result.text字段base64解码后具体信息如下,其中各元素及结果请关注:
| 参数名 | 类型 | 描述 | 备注 |
|---|---|---|---|
| place | array | 场所分类结果 | |
| place[n].frameID | int | 图像帧号 | 预留字段,无需特别关注 |
| place[n].startTimeOffset | float | 开始时间偏移量 | 预留字段,无需特别关注 |
| place[n].entity | array | top-n分类结果 | 图像的top-n分类结果,按置信度由高到低排序 |
| place[n].entity[n].score | float | 置信度 | 当前分类结果的置信度(范围:0-1),0代表置信度最低,1代表置信度最高 |
| place[n].entity[n].name | string | 类别名 | 当前分类结果的类别名,详见下方场所分类列表。 |
| place[n].entity[n].id | int | 类别号 | 当前分类结果的类别号,详见下方场所分类列表。 |
| id | 类别名name | id | 类别名name | id | 类别名name | id | 类别名name |
|---|---|---|---|---|---|---|---|
| 0 | 航站楼 airport_terminal | 21 | 田地/农场 farm/farm_field | 42 | 售票处 ticket_booth | 63 | 树林 forest |
| 1 | 停机坪 landing_field | 22 | 果园菜园 orchard/vegetable | 43 | 露营地 campsite | 64 | 桥 bridge |
| 2 | 机舱 airplane_cabin | 23 | 牧场 pasture | 44 | 音乐工作室 music_studio | 65 | 住宅 residential_neighborhood |
| 3 | 游乐场 amusement_park | 24 | 乡村 countryside | 45 | 电梯/楼梯 elevator/staircase | 66 | 汽车展厅 auto_showroom |
| 4 | 冰场 skating_rink | 25 | 温室 greenhouse | 46 | 公园/花园 garden | 67 | 河流湖泊 lake/river |
| 5 | 舞台 arena/performance | 26 | 电视台 television_studio | 47 | 建筑工地 construction_site | 68 | 水族馆 aquarium |
| 6 | 艺术室 art_room | 27 | 亚洲寺庙 templeeast_asia | 48 | 综合超市 general_store | 69 | 沟渠 aqueduct |
| 7 | 流水线 assembly_line | 28 | 亭子 pavilion | 49 | 商店 specialized_shops | 70 | 宴会厅 banquet_hall |
| 8 | 棒球场 baseball_field | 29 | 塔 tower | 50 | 集市 bazaar | 71 | 卧室 bedchamber |
| 9 | 橄榄球场 football_field | 30 | 宫殿 palace | 51 | 图书馆/书店 library/bookstore | 72 | 山 mountain |
| 10 | 足球场 soccer_field | 31 | 西式教堂 church | 52 | 教室 classroom | 73 | 站台 station/platform |
| 11 | 排球场 volleyball_court | 32 | 街道 street | 53 | 海洋/沙滩 ocean/beach | 74 | 草地 lawn |
| 12 | 高尔夫球场 golf_course | 33 | 餐厅食堂 dining_room | 54 | 消防 firefighting | 75 | 育儿室/幼儿园 nursery |
| 13 | 田径场 athletic_field | 34 | 咖啡厅 coffee_shop | 55 | 加油站 gas_station | 76 | 美容/美发店 beauty_salon |
| 14 | 滑雪场 ski_slope | 35 | 厨房 kitchen | 56 | 垃圾场 landfill | 77 | 修理店 repair_shop |
| 15 | 篮球馆(场) basketball_court | 36 | 广场 plaza | 57 | 阳台 balcony | 78 | 斗牛场 rodeo |
| 16 | 健身房 gymnasium | 37 | 实验室 laboratory | 58 | 游戏室/娱乐室 recreation_room | 79 | 雪屋/冰雕 igloo/ice_engraving |
| 17 | 保龄球馆 bowling_alley | 38 | 酒吧 bar | 59 | 舞厅 discotheque | 80 | 车内 in_car |
| 18 | 游泳池 swimming_pool | 39 | 会议室 conference_room | 60 | 博物馆 museum | 81 | 客厅 living_room |
| 19 | 拳击场 boxing_ring | 40 | 办公室 office | 61 | 沙漠 desert/sand | 82 | 浴室/盥洗室 bath_room |
| 20 | 跑马场 racecourse | 41 | 医院 hospital | 62 | 漂流 raft | 83 | 其它 others |
base64解码后的text示例:
{"header": {"code": 0,"message": "success","sid": "ase000d60a0@hu176465263c60212882"},"payload": {"result": {"compress": "raw","encoding": "utf8","format": "json","text": "eyJwbGFjZSI6..."}}}
{"place": [{"frameID": 0,"startTimeOffset": 0.0,"entity": [{"score": 0.99022954702377319,"name": "swimming_pool","id": 18}]}]}
#错误码
备注:如出现下述列表中没有的错误码,可到 这里 查询。| 错误码 | 错误描述 | 说明 | 处理策略 |
|---|---|---|---|
| 10009 | input invalid data | 输入数据非法 | 检查输入数据 |
| 10010 | service license not enough | 没有授权许可或授权数已满 | 请到控制台提交工单联系技术人员 |
| 10019 | service read buffer timeout, session timeout | session超时 | 检查是否数据发送完毕但未关闭连接 |
| 10114 | session timeout | session 超时 | 会话时间超时,检查是否发送数据时间超过了60s |
| 10139 | invalid param | 参数错误 | 检查参数是否正确 |
| 10160 | parse request json error | 请求数据格式非法 | 检查请求数据是否是合法的json |
| 10161 | parse base64 string error | base64解码失败 | 检查发送的数据是否使用base64编码了 |
| 10163 | param validate error:… | 参数校验失败 | 具体原因见详细的描述 |
| 10200 | read data timeout | 读取数据超时 | 检查是否累计10s未发送数据并且未关闭连接 |
| 10223 | RemoteLB: can’t find valued addr | lb 找不到节点 | 请到控制台提交工单联系技术人员 |
| 10313 | invalid appid | appid和apikey不匹配 | 检查appid是否合法 |
| 10317 | invalid version | 版本非法 | 请到控制台提交工单联系技术人员 |
| 10700 | not authority | 引擎异常 | 按照报错原因的描述,对照开发文档检查输入输出,如果仍然无法排除问题,请提供sid以及接口返回的错误信息,到控制台提交工单联系技术人员排查。 |
| 11200 | auth no license | 功能未授权 | 请先检查appid是否正确,并且确保该appid下添加了相关服务。若没问题,则按照如下方法排查。 1. 确认总调用量是否已超越限制,或者总次数授权已到期,若已超限或者已过期请联系商务人员。 2. 查看是否使用了未授权的功能,或者授权已过期。 |
| 11201 | auth no enough license | 该APPID的每日交互次数超过限制 | 根据自身情况提交应用审核进行服务量提额,或者联系商务购买企业级正式接口,获得海量服务量权限以便商用。 |
#调用示例
注: demo只是一个简单的调用示例,不适合直接放在复杂多变的生产环境使用
注: 其他开发语言请参照 接口调用流程 进行开发,也欢迎热心的开发者到 讯飞开放平台社区 分享你们的demo。
