API调用方法
更新时间：2023-11-29
简介
本文档主要说EasyDL零售版的货架拼接服务API如何使用，如有疑问可以通过以下方式联系我们：
- 在百度智能云控制台内提交工单，咨询问题类型请选择人工智能服务
- 进入EasyDL社区交流，与其他开发者进行互动
API总览
接口列表
任务状态 task_status
| 状态 | 描述 |
|---|---|
| Created | 已创建的任务 |
| Queued | 排队中的任务 |
| Running | 正在拼接的任务 |
| Success | 拼接成功的任务 |
| Failure | 拼接失败的任务 |
| Terminated | 被手动终止的任务 |
启动任务后，免费阶段，无论任务成功、失败、终止均会消耗免费任务数；付费使用阶段，仅对拼接成功和手动终止的任务进行计费。
接口鉴权
- 进入EasyDL零售版的百度智能云控制台应用列表页面，如下图所示：
- 如果还未创建应用，请点击「创建应用」按钮进行创建。创建应用后，参考鉴权参考文档，使用API Key(AK)和Secret Key(SK)获取access_token
API使用方法
创建任务API
接口描述
创建货架拼接任务，开始整个拼接的流程。
请求说明
请求示例
HTTP 方法：POST
接口URL：https://aip.baidubce.com/rpc/2.0/ai_custom_retail/v1/tasks/image_stitch/create
URL参数：
| 参数 | 值 |
|---|---|
| access_token | 通过API Key和Secret Key获取的access_token，参考鉴权认证机制文档 |
Header如下：
| 参数 | 值 |
|---|---|
| Content-Type | application/json |
Body中放置请求参数，参数详情如下：
请求参数
| 参数名称 | 是否必需 | 参数类型 | 描述 | 参数值限制 |
|---|---|---|---|---|
| api_url | 是 | string | 商品检测服务的url | 无 |
| row_image_nums | 是 | array[number] | 各行待拼接货架图片的数量，array长度为货架图片的行数，array[i]为第i行的货架图片数量 | 行数不大于3，行内图片数量不大于60 |
| detection_threshold | 否 | float | 商品检测服务的阈值 | 默认值为商品检测服务的阈值，取值范围[0，1] |
| nms_iou_threshold | 否 | float | 检测框矫准去重的阈值 | 默认值为0.3, 取值范围[0.2,0.8] |
Body请求示例：
{
"api_url": "http://xxxxx",
"row_image_nums": [3, 3, 4],
"detection_threshold": 0.3,
"nms_iou_threshold"：0.45
}返回说明
返回参数
| 参数名称 | 是否必需 | 参数类型 | 描述 |
|---|---|---|---|
| log_id | 是 | number | 唯一的log id，用于问题定位 |
| error_code | 否 | number | 错误码 |
| error_msg | 否 | string | 错误描述 |
| task_id | 否 | string | 新建任务对应的id |
| log_task_id | 否 | string | 用于demo显示的任务id,用于问题定位 |
| task_status | 否 | string | 任务状态 |
Body返回示例：
{
"log_id": xxxxxx,
"task_id": "xxxxx",
"log_task_id": "xxx",
"task_status": "Created"
}
{
"log_id": xxxx,
"error_code": 336204,
"error_msg": "api name authentication failed"
}上传图片API
接口描述
为指定任务上传待拼接的货架图
提示：只有在Created状态的任务才可以上传图片
请求说明
请求示例
HTTP 方法：POST
接口URL：https://aip.baidubce.com/rpc/2.0/ai_custom_retail/v1/tasks/image_stitch/upload
URL参数：
| 参数 | 值 |
|---|---|
| access_token | 通过API Key和Secret Key获取的access_token，参考鉴权认证机制文档 |
Header如下：
| 参数 | 值 |
|---|---|
| Content-Type | application/json |
Body中放置请求参数，参数详情如下：
请求参数
| 参数名称 | 是否必需 | 参数类型 | 描述 | 参数值限制 |
|---|---|---|---|---|
| task_id | 是 | string | 货架拼接任务id | 无 |
| row | 是 | number | 图片对应行的index | 取值从0开始，需小于创建任务参数row_image_nums的长度 |
| column | 是 | number | 图片在行内所在的index | 取值从0开始，需小于创建任务参数row_image_nums[row]的取值 |
| image | 是 | string | 上传图片的base64编码 | 图像数据，base64编码，要求base64编码后大小不超过4M，最短边至少15px，最长边最大4096px,支持jpg/png/bmp格式 注意请去掉头部 |
Body请求示例：
{
"task_id": "xxxx",
"row": 1,
"column": 2,
"image": "xxx=="
}返回说明
接口返回参数：
| 参数名称 | 是否必需 | 参数类型 | 描述 |
|---|---|---|---|
| log_id | 是 | number | 唯一的log id，用于问题定位 |
| error_code | 否 | number | 错误码 |
| error_msg | 否 | string | 错误描述 |
| task_status | 否 | string | 任务状态 |
Body返回示例：
{
"log_id": xxxx,
"task_status": "Created"
}
{
"log_id": xxxxx,
"error_code": 336201,
"error_msg": "unknown task id"
}开始任务API
接口描述
开始执行货架拼接任务
提示：只有在Created状态的任务可以启动，若启动任务数到达用户的上限（默认为1，即同时只可以启动一个拼接任务），任务进入Queued状态。
请求说明
请求示例
HTTP 方法：POST
接口URL：https://aip.baidubce.com/rpc/2.0/ai_custom_retail/v1/tasks/image_stitch/start
URL参数：
| 参数 | 值 |
|---|---|
| access_token | 通过API Key和Secret Key获取的access_token，参考鉴权认证机制文档 |
Header如下：
| 参数 | 值 |
|---|---|
| Content-Type | application/json |
Body中放置请求参数，参数详情如下：
请求参数
| 参数名称 | 是否必需 | 参数类型 | 描述 |
|---|---|---|---|
| task_id | 是 | string | 货架拼接任务id |
Body请求示例：
{
"task_id": "xxxx"
}返回说明
返回参数
| 参数名称 | 是否必需 | 参数类型 | 描述 |
|---|---|---|---|
| log_id | 是 | number | 唯一的log id，用于问题定位 |
| error_code | 否 | number | 错误码 |
| error_msg | 否 | string | 错误描述 |
| task_status | 否 | string | 任务状态 |
| missed_location | 否 | array | 缺失图片对应行和列的index |
Body返回示例：
{ # 启动成功
"log_id": xxxx,
"task_status": "Running"
}
{ # 用户已运行的货架拼接任务已达上限，排队等待
"log_id": xxxx,
"task_status": "Queued"
}
{ # 货架图片未全部上传
"log_id": xxxx,
"error_code": 336211,
"error_msg": "some images missed",
"missed_location": [[0, 2], [1, 3]] # [[row, column]...]
}查询结果API
接口描述
查询任务运行的状态或者结果信息
请求说明
请求示例
HTTP 方法：POST
接口URL：https://aip.baidubce.com/rpc/2.0/ai_custom_retail/v1/tasks/image_stitch/query
URL参数：
| 参数 | 值 |
|---|---|
| access_token | 通过API Key和Secret Key获取的access_token，参考鉴权认证机制文档 |
Header如下：
| 参数 | 值 |
|---|---|
| Content-Type | application/json |
Body中放置请求参数，参数详情如下：
请求参数
| 参数名称 | 是否必需 | 参数类型 | 描述 | 参数值限制 |
|---|---|---|---|---|
| task_id | 是 | string | 货架拼接任务id | 无 |
Body请求示例：
{
"task_id": "xxxx"
}返回说明
返回参数
| 参数名称 | 是否必需 | 参数类型 | 描述 |
|---|---|---|---|
| log_id | 是 | number | 唯一的log id，用于问题定位 |
| error_code | 否 | number | 错误码 |
| error_msg | 否 | string | 错误描述 |
| log_task_id | 否 | string | 用于demo显示的任务id,用于问题定位 |
| task_status | 否 | string | 任务状态 |
| task_result | 否 | dict | 任务拼接结果 |
| +image_url | 否 | string | 拼接成功后大图的url |
| +preview_image_url | 否 | string | 拼接成功后大图预览图的url，压缩到1M以下，用于快速预览 |
| +bbox | 否 | array | 在拼接大图上的商品检测框 |
| ++name | 否 | string | 商品名称 |
| ++score | 否 | float | 检测框置信度 |
| ++sku_code | 否 | string | 商品对应的sku code |
| ++location | 否 | dict | 检测框的位置 |
| +++left | 否 | number | 检测框的左上角像素点的横坐标 |
| +++top | 否 | number | 检测框的左上角像素点的纵坐标 |
| +++height | 否 | number | 检测框的高度 |
| +++width | 否 | number | 检测框的宽度 |
| +sku_stat_info | 否 | array | 在拼接大图上的商品检测框的统计信息 |
| ++name | 否 | string | 商品名称 |
| ++sku_code | 否 | string | 商品对应的sku code |
| ++count | 否 | number | 检测对应商品的数量 |
| ++proportion | 否 | float | 统计商品在完整图片中的排面占比 |
| +stitch_error_code | 否 | array[number] | 拼接错误码 |
| +fail_msg | 否 | string | 拼接失败的错误信息 |
stitch_error_code取值
| stitch_error_code | 描述 |
|---|---|
| 0 | 拼接成功 |
| 100 | 水平矫正失败 |
| 200 | 竖直矫正失败 |
| 300 | 拼接失败，可能原因相邻图像重叠度不足30% |
| 400 | 显存不足(OOM)，图片数量过多 |
| 500 | GPU所能分配的单张图片的显存不足，单张图片太大 |
Body返回示例：
{ # 任务(已创建/排队中/运行中/已取消)
"log_id": xxxx,
"log_task_id": "xxx",
"task_status": "Created/Queued/Running/Terminated"
}
{ # 拼接任务运行成功
"log_id": xxxx,
"log_task_id": "xxx",
"task_status": "Success",
"task_result": {
"image_url": "https://xxxx",
"preview_image_url": "https://xxxx",
"bbox": [{
"name": "xxx",
"score": xxx,
"sku_code": "xxx",
"location": {
"left": xxx,
"top": xxx,
"width": xxx,
"height": xxx
}
}, ... ],
"sku_stat_info":[{
"sku_code": "xxx",
"name": "xxx",
"count": n
}, ...],
"stitch_error_code": [100, ...]
}
}
{ # 拼接任务运行失败
"log_id": xxxx,
"log_task_id": "xxx",
"task_status": "Failure"，
"task_result": {
"fail_msg": "image stitch job running timeout"
}
}
{ # 请求错误
"log_id": xxxx,
"error_code": 336201,
"error_msg": "unknown task id"
}终止任务API
接口描述
终止正在进行或者排队的任务
请求说明
请求示例
HTTP 方法：POST
接口URL：https://aip.baidubce.com/rpc/2.0/ai_custom_retail/v1/tasks/image_stitch/terminate
URL参数：
| 参数 | 值 |
|---|---|
| access_token | 通过API Key和Secret Key获取的access_token，参考鉴权认证机制文档 |
Header如下：
| 参数 | 值 |
|---|---|
| Content-Type | application/json |
Body中放置请求参数，参数详情如下：
请求参数
| 参数名称 | 是否必需 | 参数类型 | 描述 | 参数值限制 |
|---|---|---|---|---|
| task_id | 是 | string | 货架拼接任务id | 无 |
Body请求示例：
{
"task_id": "xxxx"
}返回说明
返回参数
| 参数名称 | 是否必需 | 参数类型 | 描述 |
|---|---|---|---|
| log_id | 是 | number | 唯一的log id，用于问题定位 |
| error_code | 否 | number | 错误码 |
| error_msg | 否 | string | 错误描述 |
| task_status | 否 | string | 任务状态 |
Body返回示例：
{
"log_id": xxxx,
"task_status": "Terminated"
}任务列表API
接口描述
根据查询条件查询任务列表，多个条件取交集；按照创建时间倒序。
请求说明
请求示例
HTTP 方法：POST
接口URL：https://aip.baidubce.com/rpc/2.0/ai_custom_retail/v1/tasks/image_stitch/list
URL参数：
| 参数 | 值 |
|---|---|
| access_token | 通过API Key和Secret Key获取的access_token，参考鉴权认证机制文档 |
Header如下：
| 参数 | 值 |
|---|---|
| Content-Type | application/json |
Body中放置请求参数，参数详情如下：
请求参数
| 参数名称 | 是否必需 | 参数类型 | 描述 | 参数值限制 |
|---|---|---|---|---|
| task_ids | 否 | array[string] | 只返回指定id的任务信息 | 无 |
| begin_time | 否 | number | 只返回begin_time以后创建的任务信息 | 时间戳 |
| end_time | 否 | number | 只返回end_time之前创建的任务信息 | 时间戳 |
Body请求示例：
{
"task_ids": ["xx", "xxx"],
"begin_time": 1562763431,
"end_time": 1562763842
}返回说明
返回参数
| 参数名称 | 是否必需 | 参数类型 | 描述 |
|---|---|---|---|
| log_id | 是 | number | 唯一的log id，用于问题定位 |
| error_code | 否 | number | 错误码 |
| error_msg | 否 | string | 错误描述 |
| tasks_info | 否 | array | 任务列表 |
| +task_id | 否 | string | 任务id |
| +log_task_id | 否 | string | 用于demo显示的任务id,用于问题定位 |
| +task_status | 否 | string | 任务状态 |
| +create_time | 否 | number | 任务创建时间 |
Body返回示例：
{
"log_id": xxxx,
"tasks_info": [
{
"task_id": "xxx",
"log_task_id": "xxx",
"task_status": "Created/Queued/Running/...",
"create_time": 1562763842
}, ...
]
}