API调用方法

更新时间：2023-11-29

简介

本文档主要说EasyDL零售版的货架拼接服务API如何使用，如有疑问可以通过以下方式联系我们：

在百度智能云控制台内提交工单，咨询问题类型请选择人工智能服务
进入EasyDL社区交流，与其他开发者进行互动

API总览

接口列表

API名称	描述	API
创建任务	开始拼接整个流程	https://aip.baidubce.com/rpc/2.0/ai_custom_retail/v1/tasks/image_stitch/create
上传图片	上传货架局部图片	https://aip.baidubce.com/rpc/2.0/ai_custom_retail/v1/tasks/image_stitch/upload
开始任务	启动货架拼接离线任务	https://aip.baidubce.com/rpc/2.0/ai_custom_retail/v1/tasks/image_stitch/start
查询结果	查询任务运行状态或者结果	https://aip.baidubce.com/rpc/2.0/ai_custom_retail/v1/tasks/image_stitch/query
终止任务	终止正在进行或者等待的任务	https://aip.baidubce.com/rpc/2.0/ai_custom_retail/v1/tasks/image_stitch/terminate
任务列表	列出所有状态的任务列表	https://aip.baidubce.com/rpc/2.0/ai_custom_retail/v1/tasks/image_stitch/list

任务状态 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
		}, ...
	]
}

错误码

SDK文档

百度智能云

EasyDL零门槛AI开发平台

EasyDL零门槛AI开发平台

API调用方法

简介

API总览

接口列表

任务状态 task_status

接口鉴权

API使用方法

创建任务API

接口描述

请求说明

返回说明

上传图片API

接口描述

请求说明

返回说明

开始任务API

接口描述

请求说明

返回说明

查询结果API

接口描述

请求说明

返回说明

终止任务API

接口描述

请求说明

返回说明

任务列表API

接口描述

请求说明

返回说明