场景识别 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。