创建应用

创建REST API物体识别应用

1. 登录 习悦开发者平台,进入 控制台 页面,点击“创建应用”按钮,如图:

2. 填写应用相关信息,“应用服务”需要勾选物体识别,以获得相关权限,否则在开发过程将提示缺少权限,勾选“REST API”应用平台,点击“提交应用”,如图:

3. 在我的应用模块可以查看已创建的应用及应用信息,如图:

REST API 开发

开始开发

1. 在我的应用模块,获取应用的API Key 与 API Secret;

2. 调用平台授权认证接口 /auth/token,分别填入apiKey和apiSecret,对应上图API Key 、API Secret,获取平台认证accessToken,用于其他请求的合法校验,否则平台将视为非法请求。

请求示例:

https://dev.zhthinkjoy.com/api/auth/token?apiKey=您的API Key&apiSecret=您的API Secret

响应示例:

{
  "resCode": "0",
  "resMsg": "SUCCESS",
  "resData": {
    "expireSecond": "1800",
    "accessToken": "7eb6cbc3bd6cd8707d4c98a7fc7bd42fce4ec461"
  }
}

注:accessToken具有时效,有效时间为expireSecond,单位:秒,开发者需要维护accessToken有效性,在失效时需要重新调用该接口获取有效的accessToken,以保证请求合法性。


3. 根据物体识别接口进行对接,请求均为 POST 请求,参数放于 Body 中,采用 form-data 形式。

获取token

请求URL

https://dev.zhthinkjoy.com/api/auth/token

请求方式

POST

描述

在进行其他操作前需要根据apiKey和apiSecret获取时效为30分钟的token作为认证信息。

参数

参数名 参数类型 备注
必须 apiKey String 账户的API KEY
apiSecret String 账户的API SECRET

返回值说明

字段 类型 描述
resCode String 0表示正常返回, 其他编码表示发生异常
resMsg String 成功操作返回SUCCESS, 否则返回错误提示信息
resData Object Token信息包
expireSecond: 有效时间,单位秒;
accessToken;

成功返回示例

{
  "resCode": "0",
  "resMsg": "SUCCESS",
  "resData": {
    "expireSecond": "1800",
    "accessToken": "e36ae62735f2936ba6c95e272a3d03c93bcca751"
  }
}

物体识别 (Image)

请求URL

https://dev.zhthinkjoy.com/api/objectApp/detectByFile

请求方式

POST

描述

上传File类型的图片,对图片中的物体进行识别,返回最相似的物体名称和相似度。

参数

参数名 参数类型 备注
必须 accessToken String 访问token
file File 图片文件
可选 classes String 希望识别的物体类型,多个类型时使用英文逗号(,)隔开。
类型参考
topNum int 最大返回数,参数范围大于0的整数;如填入5,则只返回识别到的前五个数据。
threshold double 置信值,参数范围[0.0,1.0],默认值0.5;如填入0.6,则只返回相似度大于0.6的数据。

返回值说明

字段 类型 描述
resCode String 0表示正常返回, 其他编码表示发生异常
resMsg String 成功操作返回SUCCESS, 否则返回错误提示信息
resData Object 分析数据
objectData List 物体识别数据
cate String 物体英文名
alias String 物体中文名
ref String 冗余字段
x float 物体中心点x坐标
y float 物体中心点y坐标
width float 图片的比例宽
height float 图片的比例高
pro double 相似度
msgId String 唯一请求ID

成功返回示例

{
  "resCode": "0",
  "resMsg": "SUCCESS",
  "resData": {
    "objectData": [
      {
        "cate": "potted plant",
        "ref": "",
        "x": 0.90366393,
        "width": 0.1250177,
        "alias": "盆栽",
        "y": 0.68221331,
        "pro": 0.58021277189254761,
        "height": 0.2857618
      },
      {
        "cate": "chair",
        "ref": "",
        "x": 0.75355732,
        "width": 0.13004409,
        "alias": "椅子",
        "y": 0.62903124,
        "pro": 0.30216532945632935,
        "height": 0.1584253
      },
      {
        "cate": "potted plant",
        "ref": "",
        "x": 0.22152928,
        "width": 0.16491376,
        "alias": "盆栽",
        "y": 0.50714159,
        "pro": 0.28669875860214233,
        "height": 0.62810874
      }
    ],
    "msgId": "645dae0d-d842-494a-adb0-b0d103e3d9e6"
  }
}

状态码

状态码 异常信息 可能情况
0 SUCCESS 成功
1201 MISSING_ARGUMENTS 缺少必要参数
1202 INVALID_ARGUMENTS 参数非法
1800 HTTP_ERROR http链接错误
1900 ERROR 服务错误
1904 NO_CONTENT 未检测到内容
1952 ERROR_SIZE 错误图片大小
1954 NOT_AUTH 错误的accessToken,或者accessToken已失效
1955 NOT_UNPACK 图片无法解压

物体识别 (Base64)

请求URL

https://dev.zhthinkjoy.com/api/objectApp/detectByBase64

请求方式

POST

描述

上传Base64编码字符串,对图片中的物体进行识别,返回最相似的物体名称和相似度。

参数

参数名 参数类型 备注
必须 accessToken String 访问token
base64Str String 图片文件的base64编码
图片转Base64示例(仅供参考)>>
可选 classes String 识别类型,多个类型时使用英文逗号(,)隔开。
类型参考
topNum int 最大返回数,参数范围大于0的整数;如填入5,则只返回识别到的前五个数据。
threshold double 置信值,参数范围[0.0,1.0],默认值0.5;如填入0.6,则只返回相似度大于0.6的数据。

返回值说明

字段 类型 描述
resCode String 0表示正常返回, 其他编码表示发生异常
resMsg String 成功操作返回SUCCESS, 否则返回错误提示信息
resData Object 分析数据
objectData List 物体识别数据
cate String 物体英文名
alias String 物体中文名
ref String 冗余字段
x float 物体中心点x坐标
y float 物体中心点y坐标
width float 图片的比例宽
height float 图片的比例高
pro double 相似度
msgId String 唯一请求ID

成功返回示例

{
  "resCode": "0",
  "resMsg": "SUCCESS",
  "resData": {
    "objectData": [
      {
        "cate": "potted plant",
        "ref": "",
        "x": 0.90366393,
        "width": 0.1250177,
        "alias": "盆栽",
        "y": 0.68221331,
        "pro": 0.58021277189254761,
        "height": 0.2857618
      },
      {
        "cate": "chair",
        "ref": "",
        "x": 0.75355732,
        "width": 0.13004409,
        "alias": "椅子",
        "y": 0.62903124,
        "pro": 0.30216532945632935,
        "height": 0.1584253
      },
      {
        "cate": "potted plant",
        "ref": "",
        "x": 0.22152928,
        "width": 0.16491376,
        "alias": "盆栽",
        "y": 0.50714159,
        "pro": 0.28669875860214233,
        "height": 0.62810874
      }
    ],
    "msgId": "645dae0d-d842-494a-adb0-b0d103e3d9e6"
  }
}

状态码

状态码 异常信息 可能情况
0 SUCCESS 成功
1201 MISSING_ARGUMENTS 缺少必要参数
1202 INVALID_ARGUMENTS 参数非法
1800 HTTP_ERROR http链接错误
1900 ERROR 服务错误
1904 NO_CONTENT 未检测到内容
1952 ERROR_SIZE 错误图片大小
1954 NOT_AUTH 错误的accessToken,或者accessToken已失效
1955 NOT_UNPACK 图片无法解压

物体识别 (URL)

请求URL

https://dev.zhthinkjoy.com/api/objectApp/detectByURL

请求方式

POST

描述

对图片中的物体进行识别,返回最相似的物体名称和相似度。

参数

参数名 参数类型 备注
必须 accessToken String 访问token
imageURL String 分辨率小于1920*1920 JPG(JPEG)/PNG图片文件的URL链接
选填 classes String 识别类型,多个类型时使用英文逗号(,)隔开。
类型参考
topNum int 最大返回数,参数范围大于0的整数;如填入5,则只返回识别到的前五个数据。
threshold double 置信值,参数范围[0.0,1.0],默认值0.5;如填入0.6,则只返回相似度大于0.6的数据。

返回值说明

字段 类型 描述
resCode String 0表示正常返回, 其他编码表示发生异常
resMsg String 成功操作返回SUCCESS, 否则返回错误提示信息
resData Object 分析数据
objectData List 物体识别数据
cate String 物体英文名
alias String 物体中文名
ref String 冗余字段
x float 物体中心点x坐标
y float 物体中心点y坐标
width float 图片的比例宽
height float 图片的比例高
pro double 相似度
msgId String 唯一请求ID

成功返回示例

{
  "resCode": "0",
  "resMsg": "SUCCESS",
  "resData": {
    "objectData": [
      {
        "cate": "potted plant",
        "ref": "",
        "x": 0.90366393,
        "width": 0.1250177,
        "alias": "盆栽",
        "y": 0.68221331,
        "pro": 0.58021277189254761,
        "height": 0.2857618
      },
      {
        "cate": "chair",
        "ref": "",
        "x": 0.75355732,
        "width": 0.13004409,
        "alias": "椅子",
        "y": 0.62903124,
        "pro": 0.30216532945632935,
        "height": 0.1584253
      },
      {
        "cate": "potted plant",
        "ref": "",
        "x": 0.22152928,
        "width": 0.16491376,
        "alias": "盆栽",
        "y": 0.50714159,
        "pro": 0.28669875860214233,
        "height": 0.62810874
      }
    ],
    "msgId": "645dae0d-d842-494a-adb0-b0d103e3d9e6"
  }
}

状态码

状态码 异常信息 可能情况
0 SUCCESS 成功
1201 MISSING_ARGUMENTS 缺少必要参数
1202 INVALID_ARGUMENTS 参数非法
1800 HTTP_ERROR http链接错误
1900 ERROR 服务错误
1904 NO_CONTENT 未检测到内容
1952 ERROR_SIZE 错误图片大小
1954 NOT_AUTH 错误的accessToken,或者accessToken已失效
1955 NOT_UNPACK 图片无法解压

classes参数

参数名 说明
person 人类
bicycle 自行车
car 轿车
motorcycle 摩托车
airplane 飞机
bus 巴士
train 火车
truck 卡车
boat
traffic light 红绿灯
fire hydrant 消防栓
stop sign 停车标志
parking meter 停车计时器
bench 长凳
bird
cat
dog
horse
sheep
cow 奶牛
elephant 大象
bear
zebra 斑马
giraffe 长颈鹿
backpack 背包
umbrella 雨伞
handbag 手提包
tie 领带
suitcase 手提箱
frisbee 飞盘
skis 雪橇
snowboard 滑雪板
sports ball 运动球
kite 风筝
baseball bat 棒球棒
baseball glove 棒球手套
skateboard 滑板
surfboard 冲浪板
tennis racketv 网球拍
bottle 瓶子
wine glass 酒杯
cup 杯子
fork 餐叉
knife 餐刀
spoon 汤匙
bowl
banana 香蕉
apple 苹果
sandwich 三文治
orange 橙子
broccoli 花椰菜
carrot 胡萝卜
hot dog 热狗
pizza 披萨
donut 甜甜圈
cake 蛋糕
chair 椅子
couch 沙发
potted plant 盆栽
bed
dining table 餐桌
toilet 马桶
display 显示器
laptop 笔记本电脑
mouse 鼠标
remote 遥控器
keyboard 键盘
cell phone 手机
microwave 微波炉
oven 烤箱
toaster 烤面包机
sink 水槽
refrigerator 冰箱
book 书籍
clock 时钟
vase 花瓶
scissors 剪刀
teddy bear 泰迪熊
hair drier 电吹风
toothbrush 牙刷
Q群
咨询