API调用方法
接口总览
1.图片管理接口
| 接口名称 | API URL | API描述 |
|---|---|---|
| 创建图集API | https://aip.baidubce.com/rpc/2.0/ai_custom_retail/v1/tasks/image_similar/create_dataset | 创建图集，获取图集ID |
| 上传图片API | https://aip.baidubce.com/rpc/2.0/ai_custom_retail/v1/tasks/image_similar/upload | 指定图集ID，将需要识别的图片上传至该图集 |
| 图集列表API | https://aip.baidubce.com/rpc/2.0/ai_custom_retail/v1/tasks/image_similar/dataset_list | 查询已创建的图集和状态 |
图集状态 dataset_status
| 状态 | 描述 |
|---|---|
| Idle | 空闲状态，可被使用的图集 |
| Processing | 正在运行或是排队中的任务涉及的图集 |
2.任务管理接口
| 接口名称 | API URL | API描述 |
|---|---|---|
| 创建任务API | https://aip.baidubce.com/rpc/2.0/ai_custom_retail/v1/tasks/image_similar/create_task | 创建窜拍识别任务，获取任务ID |
| 查询结果API | https://aip.baidubce.com/rpc/2.0/ai_custom_retail/v1/tasks/image_similar/query | 指定任务ID，查询任务状态和结果 |
| 任务列表API | https://aip.baidubce.com/rpc/2.0/ai_custom_retail/v1/tasks/image_similar/task_list | 查询已创建的任务和状态 |
任务状态 task_status
| 状态 | 描述 |
|---|---|
| Queued | 排队中的任务 |
| Running | 正在运行的任务 |
| Success | 运行成功的任务 |
| Failure | 运行失败的任务 |
接口调用流程
1.创建图集，获得图集ID
创建图集API：https://aip.baidubce.com/rpc/2.0/ai_custom_retail/v1/tasks/image_similar/create_dataset
2.指定图集ID，把要识别窜拍的图片上传到该图集
上传图片API：https://aip.baidubce.com/rpc/2.0/ai_custom_retail/v1/tasks/image_similar/upload
3.创建任务，指定图集ID，对该图集做窜拍识别，获取任务ID
创建任务API：https://aip.baidubce.com/rpc/2.0/ai_custom_retail/v1/tasks/image_similar/create_task
4.指定任务ID，轮询任务结果，可以每隔一定时间调用API查询任务结果，比如10s查询一次，任务完成后可以查到结果
查询结果API：https://aip.baidubce.com/rpc/2.0/ai_custom_retail/v1/tasks/image_similar/query
另外，可通过图集列表API和任务列表API查询所有图集和任务。
接口调用方法
创建图集API
1.接口描述
创建图集，用于存放需要识别窜拍的图片
2.请求说明
HTTP 方法：POST
接口URL： https://aip.baidubce.com/rpc/2.0/ai_custom_retail/v1/tasks/image_similar/create_dataset
URL参数：
| 参数 | 值 |
|---|---|
| access_token | 通过API Key和Secret Key获取的access_token，参考鉴权认证机制文档 |
Header如下：
| 参数 | 值 |
|---|---|
| Content-Type | application/json |
Body中放置请求参数，参数详情如下：
请求参数
无需上传参数
3.返回说明
返回参数
| 参数名称 | 是否必须 | 数据类型 | 含义 |
|---|---|---|---|
| log_id | 是 | int | 唯一的log id，用于问题定位 |
| dataset_id | 是 | int | 图集ID |
| dataset_status | 是 | string | 图集状态 |
上传图片API
1.接口描述
为指定图集上传需要识别窜拍的图片。仅有Idle状态的图集，可以上传图片，对Running状态的图集的上传图片报错。
2.请求说明
HTTP 方法：POST
接口URL： https://aip.baidubce.com/rpc/2.0/ai_custom_retail/v1/tasks/image_similar/upload
URL参数：
| 参数 | 值 |
|---|---|
| access_token | 通过API Key和Secret Key获取的access_token，参考鉴权认证机制文档 |
Header如下：
| 参数 | 值 |
|---|---|
| Content-Type | application/json |
Body中放置请求参数，参数详情如下：
请求参数
| 参数名称 | 是否必须 | 数据类型 | 取值范围 | 含义 |
|---|---|---|---|---|
| dataset_id | 是 | int | - | 指定上传图片的数据集id |
| image | 是 | string | - | 图像数据，base64编码，要求base64编码后大小不超过4M，最短边至少15px，最长边最大4096px,支持jpg/png/bmp格式 注意请去掉头部 |
| image_name | 是 | string | - | 图片名称或编码，请保证该字段在创建任务时定义的查窜拍范围内的唯一性 |
| image_people | 是 | string | - | 该图片的人员信息 |
| image_store | 是 | string | - | 该图片的网点信息，如ID |
| image_time | 是 | string | - | 该图片的拍摄时间，格式为“yyyy-MM-dd hh:mm:ss“ |
提示：当一张图片的image_name、image_people、image_store、image_time全都一致时，判为重复图片，后上传的直接忽略。
3.返回说明
返回参数
| 参数名称 | 是否必须 | 数据类型 | 含义 |
|---|---|---|---|
| log_id | 是 | int | 唯一的log id，用于问题定位 |
| dataset_status | 是 | string | 任务状态 |
图集列表API
1.接口描述
按条件查询创建的图集信息
2.请求说明
HTTP 方法：POST
接口URL： https://aip.baidubce.com/rpc/2.0/ai_custom_retail/v1/tasks/image_similar/dataset_list
URL参数：
| 参数 | 值 |
|---|---|
| access_token | 通过API Key和Secret Key获取的access_token，参考鉴权认证机制文档 |
Header如下：
| 参数 | 值 |
|---|---|
| Content-Type | application/json |
Body中放置请求参数，参数详情如下：
请求参数
| 参数名称 | 是否必需 | 参数类型 | 描述 |
|---|---|---|---|
| dataset_ids | 否 | array[string] | 只返回指定id的任务信息，最多返回前200个dataset_id的结果 |
| begin_time | 否 | number | 时间戳，只返回begin_time以后创建的任务信息 |
| end_time | 否 | number | 时间戳，只返回end_time之前创建的任务信息 |
3.返回说明
返回参数
| 参数名称 | 是否必需 | 参数类型 | 描述 |
|---|---|---|---|
| log_id | 是 | int | 唯一的log id，用于问题定位 |
| dataset_info | 否 | array[dict] | 任务列表，最多返回前200个dataset_id的结果 |
| +dataset_id | 否 | string | 任务id |
| +dataset_status | 否 | string | 任务状态 |
| +create_time | 否 | int | 时间戳，图集创建时间 |
| +image_num | 否 | int | 图集中含有的图片数量 |
创建任务API
1.接口描述
创建窜拍识别任务。
2.请求说明
HTTP 方法：POST
接口URL： https://aip.baidubce.com/rpc/2.0/ai_custom_retail/v1/tasks/image_similar/create_task
URL参数：
| 参数 | 值 |
|---|---|
| access_token | 通过API Key和Secret Key获取的access_token，参考鉴权认证机制文档 |
Header如下：
| 参数 | 值 |
|---|---|
| Content-Type | application/json |
Body中放置请求参数，参数详情如下：
请求参数
| 参数名称 | 是否必须 | 数据类型 | 取值范围 | 含义 |
|---|---|---|---|---|
| dataset_id | 是 | int | - | 指定需要进行识别窜拍的图集ID |
| threshold | 否 | array[float] | 每个元素取值范围为0.60~1.00 | 例如：[0.8,0.95]。可精确到小数点后两位。阈值为界定两张图视为窜拍的score的阈值，当score大于threshold时，则判定为疑似窜拍结果返回。不填，默认为0.8 |
| task_people | 否 | boolean | “True”、“False” | 区分不同人员，在同一人员拍摄的图片范围内，识别窜拍。True为区分，False为不区分；不填，默认为False |
| task_store | 否 | string | “undefined”、“within” | “undefined”表示不区分网点；within表示区分不同网点，在同一网点的图片范围内，识别窜拍；不填，默认为“undefined” |
| task_time | 否 | string | “undefined”、“year”、“month”、“day” | “undefined”表示不区分年份；“year”表示区分不同年份，在同一年份内的图片范围内，识别窜拍；“month”表示区分不同月份（不同年同月，算作不同月），在同一月份内的图片范围内，识别窜拍；“day” 表示区分不同日子（不同年或不同月的同一日，算作不同日），在同一日子内的图片范围内，识别窜拍。不填，默认为“undefined” |
3.返回说明
返回参数
| 参数名称 | 是否必须 | 数据类型 | 含义 |
|---|---|---|---|
| log_id | 是 | int | 唯一的log id，用于问题定位 |
| task_id | 否 | string | 新建任务对应的id |
| task_status | 否 | string | 任务状态 |
查询结果API
1.接口描述
查询指定任务的结果。
2.请求说明
HTTP 方法：POST
接口URL： https://aip.baidubce.com/rpc/2.0/ai_custom_retail/v1/tasks/image_similar/query
URL参数：
| 参数 | 值 |
|---|---|
| access_token | 通过API Key和Secret Key获取的access_token，参考鉴权认证机制文档 |
Header如下：
| 参数 | 值 |
|---|---|
| Content-Type | application/json |
Body中放置请求参数，参数详情如下：
请求参数
| 参数名称 | 是否必须 | 数据类型 | 取值范围 | 含义 |
|---|---|---|---|---|
| task_id | 是 | string | - | 任务对应的id |
3.返回说明
返回参数
| 参数名称 | 是否必须 | 数据类型 | 含义 |
|---|---|---|---|
| log_id | 是 | int | 唯一的log id，用于问题定位 |
| task_status | 否 | string | 任务状态 |
| task_results_url | 否 | dict | dict的key为阈值，value为结果文件URL，文件格式为json。url每次查询随机生成，有效期7天 |
文件内的参数
| 参数名称 | 是否必须 | 数据类型 | 含义 |
|---|---|---|---|
| task_results | 否 | array[dict] | 任务结果 |
| +re_people | 否 | string | 当创建任务「task_people」为true时，返回人员信息，与用户上传时传上的「img_people」一致；当「task_people」为false时，返回-1 |
| +re_store | 否 | string | 当创建任务「task_store」为“within”时，返回人员信息，网点信息，与用户上传时传上的「image_store」一致；当「task_store」为“undefined”时，返回-1 |
| +re_year | 否 | int | 当创建任务「task_time」不为“undefined”时，返回年份，与用户上传时传上的「image_time」中的“YY”一致；当「task_time」均为“undefined”时，返回-1 |
| +re_month | 否 | int | 当创建任务「task_time」为“month”或“day”时，返回月份，与用户上传时传上的「image_time」中的”MM“一致；当「task_time」为“undefined”或“year”时，返回-1 |
| +re_day | 否 | int | 当创建任务「task_time」为“day”时，返回日信息，与用户上传时传上的「image_time」中的”DD“一致；当「task_time」不为“day”时，返回-1 |
| +img_group | 否 | array[dict] | 包含的疑似相似图的信息 |
| ++group_id | 否 | int | 相似图组的组ID |
| ++img_name | 否 | array[string] | 相似图组内的包含的所有图片名称，与用户上传时传上的「image_name」一致 |
任务列表API
1.接口描述
按条件查询范围内的任务状态。
2.请求说明
HTTP 方法：POST
接口URL： https://aip.baidubce.com/rpc/2.0/ai_custom_retail/v1/tasks/image_similar/task_list
URL参数：
| 参数 | 值 |
|---|---|
| access_token | 通过API Key和Secret Key获取的access_token，参考鉴权认证机制文档 |
Header如下：
| 参数 | 值 |
|---|---|
| Content-Type | application/json |
Body中放置请求参数，参数详情如下：
请求参数
| 参数名称 | 是否必需 | 参数类型 | 描述 |
|---|---|---|---|
| task_ids | 否 | array[string] | 只返回指定id的任务信息，最多返回前200个task_id的结果 |
| begin_time | 否 | number | 时间戳，只返回begin_time以后创建的任务信息 |
| end_time | 否 | number | 时间戳，只返回end_time之前创建的任务信息 |
3.返回说明
返回参数
| 参数名称 | 是否必需 | 参数类型 | 描述 |
|---|---|---|---|
| log_id | 是 | number | 唯一的log id，用于问题定位 |
| tasks_info | 否 | array[dict] | 任务列表，最多返回前200个task_id的结果 |
| +task_id | 否 | string | 任务id |
| +task_status | 否 | string | 任务状态 |
| +create_time | 否 | number | 时间戳，任务创建时间 |