实景图管理API
更新时间：2022-05-06
简介
本文档主要说EasyDL零售版的定制商品检测服务中的实景图管理API如何使用，如有疑问可以通过以下方式联系我们：
- 在百度智能云控制台内提交工单，咨询问题类型请选择人工智能服务
- 进入EasyDL社区交流，与其他开发者进行互动
- 加入EasyDL零售版官方QQ群（群号:1009661589）联系群管
接口鉴权
- 进入EasyDL零售版的百度智能云控制台应用列表页面，如下图所示：
- 如果还未创建应用，请点击「创建应用」按钮进行创建。创建应用后，参考鉴权认证机制文档，使用API Key(AK)和Secret Key(SK)获取access_token
实景图集管理API
实景图集管理API包含以下API：
| 接口名称 | HTTP方法 | 请求Body | API URL | 说明 |
|---|---|---|---|---|
| 实景图集创建 | POST | JSON | https://aip.baidubce.com/rpc/2.0/easydl/retail/dataset/create | 用于创建实景图集 |
| 实景图集列表 | POST | JSON | https://aip.baidubce.com/rpc/2.0/easydl/retail/dataset/list | 用于列出所有实景图集，可获得实景图集的所有信息 |
| 实景图集删除 | POST | JSON | https://aip.baidubce.com/rpc/2.0/easydl/retail/dataset/delete | 用于删除指定实景图集 |
| 实景数据添加API | POST | JSON | https://aip.baidubce.com/rpc/2.0/easydl/retail/dataset/addentity | 用于为指定实景图集上传实景图片 |
实景图集创建API
接口描述
该接口可用于创建实景图集
请求说明
请求示例
HTTP 方法：POST
请求URL：https://aip.baidubce.com/rpc/2.0/easydl/retail/dataset/create
URL参数：
| 参数 | 值 |
|---|---|
| access_token | 通过API Key和Secret Key获取的access_token，参考鉴权认证机制文档 |
Header如下：
| 参数 | 值 |
|---|---|
| Content-Type | application/json |
请求参数
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| type | 是 | string | 实景图集类型，SKU_DETECTION |
| dataset_name | 是 | string | 实景图集名称，长度不超过20个utf-8字符 |
| scene | 是 | string | 应用场景，不同场景对应内容为：普通货架/货柜 general shelf/container，智能结算台 smart self-checkout，无人零售柜 smart vending machine，地堆商品 type genus，其它 other |
返回说明
返回参数
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| log_id | 是 | int | 唯一的log id，用于问题定位 |
| dataset_id | 是 | int | 创建的实景图集ID |
实景图集列表API
接口描述
该接口可用于获取已创建的实景图集列表
请求说明
请求示例
HTTP 方法：POST
请求URL：https://aip.baidubce.com/rpc/2.0/easydl/retail/dataset/list
URL参数：
| 参数 | 值 |
|---|---|
| access_token | 通过API Key和Secret Key获取的access_token，参考鉴权认证机制文档 |
Header如下：
| 参数 | 值 |
|---|---|
| Content-Type | application/json |
请求参数
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| start | 是 | int | 起始位置 |
| num | 是 | int | 结果数量 |
| type | 是 | string | 实景图集类型，SKU_DETECTION |
返回说明
返回参数
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| total_num | 是 | int | 返回结果数 |
| results | 是 | array | 返回结果 |
| +dataset_id | 是 | int | 实景图集id |
| +dataset_name | 是 | string | 实景图集名称 |
| +type | 是 | string | 实景图集类型 |
| +status | 是 | string | 实景图集状态：新建 new，上传实景图片中 uploading，错误 error，正常 normal，训练中 training |
| +special_status | 是 | string | 特殊状态，商品检测模型值为空 |
| +scene | 是 | string | 实景图集场景 |
实景数据添加API
接口描述
该接口可用于为实景图集上传标注好的图片
请求说明
请求示例
HTTP 方法：POST
请求URL：https://aip.baidubce.com/rpc/2.0/easydl/retail/dataset/addentity
URL参数：
| 参数 | 值 |
|---|---|
| access_token | 通过API Key和Secret Key获取的access_token，参考鉴权认证机制文档 |
Header如下：
| 参数 | 值 |
|---|---|
| Content-Type | application/json |
请求参数
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| dataset_id | 是 | int | 实景图集id |
| type | 是 | string | 实景图集类型，SKU_DETECTION |
| entity_content | 是 | string | 实景图片的base64编码 |
| entity_name | 是 | string | 实景图片名称 |
| appendLabel | 否 | boolean | 确定添加标签的行为：追加(true)、替换(false)。默认为追加(true) |
| labels | 否 | array | SKU标签数据，如果不传该参数，则上传的为无标注信息的图片 |
| +label_name | 否 | string | SKU标签名称，请先参考SKU创建文档完成SKU创建，格式为：SKU名称_品牌名称_规格参数，例如：雪碧_可口可乐_500ml |
| +left | 否 | int | 标注框左上角到图片左边界的距离(像素) |
| +top | 否 | int | 标注框左上角到图片上边界的距离(像素) |
| +width | 否 | int | 标注框的宽度(像素) |
| +height | 否 | int | 标注框的高度(像素) |
返回说明
返回参数
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| log_id | 是 | int | 唯一的log id，用于问题定位 |
实景图集删除API
接口描述
该接口可用于删除实景图集
请求说明
请求示例
HTTP 方法：POST
请求URL：https://aip.baidubce.com/rpc/2.0/easydl/retail/dataset/delete
URL参数：
| 参数 | 值 |
|---|---|
| access_token | 通过API Key和Secret Key获取的access_token，参考鉴权认证机制文档 |
Header如下：
| 参数 | 值 |
|---|---|
| Content-Type | application/json |
请求参数
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| dataset_id | 是 | string | 实景图集ID |
| type | 是 | string | 实景图集类型，SKU_DETECTION |
返回说明
返回参数
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| log_id | 是 | int | 唯一的log id，用于问题定位 |
错误码
若请求错误，服务器将返回的JSON文本包含以下参数：
- error_code：错误码。
- error_msg：错误描述信息，帮助理解和解决发生的错误。
例如Access Token失效返回：
{
"error_code": 110,
"error_msg": "Access token invalid or no longer valid"
}需要重新获取新的Access Token再次请求即可。
| 错误码 | 错误信息 | 描述 |
|---|---|---|
| 1 | Unknown error | 服务器内部错误，请再次请求， 如果持续出现此类错误，请通过QQ群（1009661589）或工单联系技术支持团队。 |
| 2 | Service temporarily unavailable | 服务暂不可用，请再次请求， 如果持续出现此类错误，请通过QQ群（1009661589）或工单联系技术支持团队。 |
| 3 | Unsupported openapi method | 调用的API不存在，请检查后重新尝试 |
| 4 | Open api request limit reached | 集群超限额 |
| 6 | No permission to access data | 无权限访问该用户数据 |
| 13 | Get service token failed | 获取token失败 |
| 14 | IAM Certification failed | IAM鉴权失败 |
| 15 | app not exsits or create failed | 应用不存在或者创建失败 |
| 17 | Open api daily request limit reached | 每天请求量超限额，已上线计费的接口，请直接在控制台开通计费，调用量不受限制，按调用量阶梯计费；未上线计费的接口，请通过QQ群（1009661589）联系群管手动提额 |
| 18 | Open api qps request limit reached | QPS超限额，已上线计费的接口，请直接在控制台开通计费，调用量不受限制，按调用量阶梯计费；未上线计费的接口，请通过QQ群（1009661589）联系群管手动提额 |
| 19 | Open api total request limit reached | 请求总量超限额，已上线计费的接口，请直接在控制台开通计费，调用量不受限制，按调用量阶梯计费；未上线计费的接口，请通过QQ群（1009661589）联系群管手动提额 |
| 100 | Invalid parameter | 无效的access_token参数，请检查后重新尝试 |
| 110 | Access token invalid or no longer valid | access_token无效 |
| 111 | Access token expired | access token过期 |
| 406000 | internal server error | 服务错误 |
| 406001 | param[xx] invalid | 无效的参数xx，请检查相关参数 |
| 406002 | dataset not exist | 实景图集不存在 |
| 406003 | dataset already exists | 实景图集已存在 |
| 406004 | dataset can not be modified temporarily | 实景图集暂时不能被修改 |
| 406006 | no permission to modify the dataset | 没有修改实景图集的权限 |
| 406008 | [xx] quota exceeded | xx配额超限 |
| 406009 | sku does not exist | SKU不存在 |
| 406010 | sku already exists | SKU已存在 |
| 406011 | sku cannot be modified temporarily | SKU暂时不能被修改 |