地堆检测API调用方法
更新时间：2023-11-29
接口描述
本文档主要说明定制化商品检测模型发布后获得的API如何使用，如有疑问可以通过以下方式联系我们：
- 在百度智能云控制台内提交工单，咨询问题类型请选择人工智能服务
- 进入EasyDL社区交流，与其他开发者进行互动
接口鉴权
- 进入EasyDL零售版的百度智能云控制台应用列表页面，如下图所示：
- 如果还未创建应用，请点击「创建应用」按钮进行创建。创建应用后，参考鉴权参考文档，使用API Key(AK)和Secret Key(SK)获取access_token
请求说明
请求示例
HTTP 方法：POST
请求URL： 请首先在EasyDL零售版进行定制商品检测模型训练，完成训练后申请上线，上线成功后可在服务列表中查看并获取url。
URL参数：
| 参数 | 值 |
|---|---|
| access_token | 通过API Key和Secret Key获取的access_token，参考鉴权认证机制文档 |
Header如下：
| 参数 | 值 |
|---|---|
| Content-Type | application/json |
注意：如果出现336001和336002的错误码很可能是因为请求方式错误，与其他图像识别服务不同的是定制化图像识别服务以json方式请求。
Body请求示例：
{
"image": "<base64数据>"
}Body中放置请求参数，参数详情如下：
请求参数
| 参数 | 是否必选 | 类型 | 可选值范围 | 说明 |
|---|---|---|---|---|
| image | 是 | string | - | 图像数据，base64编码，要求base64编码后大小不超过4M，最短边至少15px，最长边最大4096px,支持jpg/png/bmp格式 注意请去掉头部 |
| threshold | 否 | number | 0~1 | 可精确到小数点后两位，默认值为建议阈值，请在 我的模型列表-完整评估结果 查看推荐阈值。阈值（threshold），是正确结果的判定标准，例如阈值是0.6，置信度大于0.6的识别结果会被当作正确结果返回。 |
提示：image参数中“去掉头部”指的是图片经base64编码后的头部信息「data:image/jpeg;base64,」，如下图所示：
返回说明
开启模型服务功能可参考服务功能文档
排面数：同层同列去重后的SKU检测数量
返回参数
| 字段 | 是否必选 | 类型 | 说明 | 需要开启的模型服务功能 |
|---|---|---|---|---|
| recapture_score | 否 | float | 图片是对手机屏幕翻拍的可能性评分。翻拍判定方法：设定一个判定为翻拍图片的阈值，即如果recapture_score大于这个值，则认为这张图片是翻拍。请结合业务实际情况和实测结果进行设定阈值 | 商品陈列翻拍识别（可选） |
| log_id | 是 | number | 唯一的log id，用于问题定位 | 商品基本信息识别（必选） |
| scenes | 否 | array(string) | 图片中包含的陈列场景类型。返回所有场景去重后的集合，“GE”表示端架，“shelf”表示货架，“freezer”表示冰柜，“TG”表示地堆，“cutbox”表示割箱，”DL“表示地龙，"HS"表示挂钩货架，"OBS"表示斜口篮货架，"SGE"表示小端架，"barcounter"表示吧台，"unknown"表示未识别到场景 | 商品陈列场景识别（可选） |
| results | 否 | array(object) | 识别结果数组 | 商品基本信息识别（必选） |
| +stack_sn | 否 | number | 堆头的序号，从左至右依次增加。举例：如果模型检测出图片存在两个堆头，那边两个堆头从左至右的stack_sn分别为1和2 | 商品基本信息识别（必选） |
| +stack_info | 否 | array(object) | 各个堆头的检测结果 | 商品基本信息识别（必选） |
| ++type | 否 | number | 堆头陈列的类型：1为KA可识别长宽；2为非KA可计数；-1为其它（不可计数和不可计长宽） | 商品基本信息识别（必选） |
| ++stack_height | 否 | number | 该堆头的高度（Y轴数量） | 商品基本信息识别（必选） |
| ++stack_width | 否 | number | 该堆头的宽度（列数，X轴数量） | 商品基本信息识别（必选） |
| ++stack_depth | 否 | number | 该堆头的纵深（Z轴数量） | 商品基本信息识别（必选） |
| ++area | 否 | number | 该堆头的占地面数量 = width * depth | 商品基本信息识别（必选） |
| ++stack_sku_num | 否 | number | 该堆头中的可识别SKU的含纵深总数量 | 商品基本信息识别（必选） |
| ++stack_sku_num_visible | 否 | number | 该堆头中的可识别SKU的可见总数量 | 商品基本信息识别（必选） |
| ++stack_sku_info | 否 | array(object) | 堆箱内含有SKU的信息 | 商品基本信息识别（必选） |
| +++name | 否 | string | SKU标签名称 | 商品基本信息识别（必选） |
| +++sku_code | 否 | string | SKU编码 | 商品基本信息识别（必选） |
| +++num_with_depth | 否 | number | 该类SKU在该堆头中的含纵深总数量 | 商品基本信息识别（必选） |
| +++num_without_depth | 否 | number | 该类SKU在该堆头中的可见总数量 | 商品基本信息识别（必选） |
| +col_info | 否 | array(object) | 各个堆头中，各列的检测结果 | 商品基本信息识别（必选） |
| ++col_loc_info | 否 | array(object) | 各列的深（Z轴）和高（Y轴）信息 | 商品基本信息识别（必选） |
| +++col_sn | 否 | array(object) | 列的序号，从左至右依次增加 | 商品基本信息识别（必选） |
| +++col_depth | 否 | number | 列的纵深（Z轴数量）SKU数量 | 商品基本信息识别（必选） |
| +++col_height | 否 | number | 列的高度（Y轴数量）SKU数量 | 商品基本信息识别（必选） |
| ++col_num_info | 否 | array(object) | 各列中各类SKU信息和数量结果 | 商品基本信息识别（必选） |
| +++col_sn | 否 | number | 列的序号，从左至右依次增加 | 商品基本信息识别（必选） |
| +++col_sku_num | 否 | number | 该列的可识别SKU的含纵深总数量 | 商品基本信息识别（必选） |
| +++col_sku_num_visible | 否 | number | 该列的可识别SKU的可见总数量 | 商品基本信息识别（必选） |
| +++col_sku_info | 否 | array(object) | 列内各类SKU的信息 | 商品基本信息识别（必选） |
| ++++name | 否 | string | SKU标签名称 | 商品基本信息识别（必选） |
| ++++sku_code | 否 | string | SKU编码 | 商品基本信息识别（必选） |
| ++++num_with_depth | 否 | number | 该类SKU在该列中的含纵深总数量 | 商品基本信息识别（必选） |
| ++++num_without_depth | 否 | number | 该类SKU在该列中的可见总数量 | 商品基本信息识别（必选） |
| ++s_col_info | 否 | array(object) | 各列中，各子列的检测结果，每个纵深（Z轴）列为一个子列 | 商品基本信息识别（必选） |
| +++col_sn | 否 | number | 列的序号，从左至右依次增加 | 商品基本信息识别（必选） |
| +++s_col_sn | 否 | number | 子列的序号，从内到外，依次增加 | 商品基本信息识别（必选） |
| +++s_col_sku_num | 否 | number | 该列的可识别SKU纵深总数量 | 商品基本信息识别（必选） |
| +++s_col_sku_num_visible | 否 | number | 该列的可识别SKU可见总数量 | 商品基本信息识别（必选）（必选） |
| +++s_col_sku_info | 否 | array(object) | 当前子列内包含SKU的信息 | 商品基本信息识别（必选） |
| ++++name | 否 | string | SKU标签名称 | 商品基本信息识别（必选） |
| ++++sku_code | 否 | string | SKU编码 | 商品基本信息识别（必选） |
| ++++num_with_depth | 否 | number | 该类SKU在该子列中的纵深总数量 | 商品基本信息识别（必选） |
| ++++num_without_depth | 否 | number | 该类SKU在该子列中的可见总数量 | 商品基本信息识别（必选） |
| +sku_info | 否 | array(object) | 该堆头中的所有商品信息 | 商品基本信息识别（必选） |
| ++name | 否 | number | SKU标签名称 | 商品基本信息识别（必选） |
| ++sku_code | 否 | number | SKU编码 | 商品基本信息识别（必选） |
| ++scene | 否 | string | 该SKU的陈列场景，“GE”表示端架，“shelf”表示货架，“freezer”表示冰柜，“TG”表示地堆，“cutbox”表示割箱，”DL“表示地龙，"HS"表示挂钩货架，"OBS"表示斜口篮货架，"SGE"表示小端架，"barcounter"表示吧台，"unknown"表示未识别到场景 | 商品陈列场景识别（可选） |
| ++score | 否 | number | 置信度 | 商品基本信息识别（必选） |
| ++location | 否 | array(object) | 该SKU在原图中的像素位置信息 | 商品基本信息识别（必选） |
| +++left | 否 | number | 检测到的目标主体区域到图片左边界的像素距离（px） | 商品基本信息识别（必选） |
| +++top | 否 | number | 检测到的目标主体区域到图片上边界的像素距离（px） | 商品基本信息识别（必选） |
| +++width | 否 | number | 检测到的目标主体区域的像素宽度（px） | 商品基本信息识别（必选） |
| +++height | 否 | number | 检测到的目标主体区域的像素高度（px） | 商品基本信息识别（必选） |
| ++threed_location | 否 | array(object) | 该SKU在堆头中的三维位置信息 | 商品基本信息识别（必选） |
| +++sku_height | 否 | number | SKU所在堆头中的3D位置，Y轴高度（从下往上数第几个SKU） | 商品基本信息识别（必选） |
| +++sku_width | 否 | number | SKU所在堆头中的3D位置，X轴宽度（从左往右数第几个SKU） | 商品基本信息识别（必选） |
| +++sku_depth | 否 | number | SKU所在堆头中的3D位置，Z轴深度（从里往外数第几个SKU） | 商品基本信息识别（必选） |
建议翻拍判定方法
设定一个判定为翻拍图片的阈值，即如果recapture的score大于这个值，则认为这张图片是翻拍。通常有两中对应的业务模式：
注：以下数值均为建议值，实际应用的阈值请结合业务实际情况和实测结果进行设定
- 业务里查翻拍的原则是宁可错杀一千，也不愿错放一个的，那么可以把认为是翻拍的阈值放在0.8~0.95。
- 业务里查翻拍的原则是允许错放过一些翻拍的图片，但是查到的一定要对，那么可以把认为是翻拍的阈值放在0.98甚至0.99。