文档首页/ 图像搜索 ImageSearch/ API参考/ API/ 搜索图片
更新时间：2023-12-11 GMT+08:00
查看PDF
分享

搜索图片

功能介绍

从图片索引库中搜索相似图片。

URI

POST /v1/{project_id}/{instance_name}/image/search

表1 路径参数

参数

是否必选

参数类型

描述

instance_name

是

String

实例名称。

project_id

是

String

用户的项目ID。获取方法请参见获取项目ID和名称。

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

是

String

用户Token。

用于获取操作API的权限。获取方法请参见获取Token接口，响应消息头中X-Subject-Token的值即为Token。
表3 请求Body参数

参数

是否必选

参数类型

描述

file

否

String

图片文件Base64编码字符串，仅支持JPEG/JPG/PNG/BMP格式，图片最小边不小于100px，最大边不超过2048px。该参数与path二选一，如果两个参数都存在，则以file为主。

path

否

String

图片的URL路径，图片库中的图片索引ID。该参数与file二选一，如果两个参数都存在，则以file为主。

limit

否

Integer

返回被检索图像的数量，取值为1~100的整数，默认为10。

最小值：1

最大值：100

缺省值：10

offset

否

Integer

偏移量，指定搜索结果返回起始位置，取值为大于或等于0的整数，默认为0。

最小值：0

tags

否

Object

图片自定义标签，最多不超过10个，格式为key：value对。 标签名（key）添加方式：

  • 登录管理控制台，单击“创建实例”，自定义标签名。
  • 登录管理控制台，在“实例管理”页签，单击实例名称，进入“基础信息”页添加自定义标签。 使用图片标签搜索时该参数必选。

is_crop

否

Boolean

是否用图片中指定区域（参数box）进行搜索。该参数目前仅对某些特定模型有效，其他模型暂不支持目标检测。 取值为true或false。

  • true：用图片中指定区域（参数box）进行搜索。
  • false：用全图进行搜索。

默认为false。

box

否

SearchBoxDetail object

图片中指定的区域。
表4 SearchBoxDetail

参数

是否必选

参数类型

描述

x

否

Integer

区域中x坐标的最小值，单位：像素。

y

否

Integer

区域中y坐标的最小值，单位：像素。

width

否

Integer

区域的宽度，单位：像素。

height

否

Integer

区域的高度，单位：像素。

响应参数

状态码： 200

表5 响应Body参数

参数

参数类型

描述

count

Integer

搜索结果总数。

result

Array of SearchPictureItem objects

搜索结果详情。
表6 SearchPictureItem

参数

参数类型

描述

path

String

被搜索图片的路径。

sim

Float

查询图片和被搜索图片的相似度，值越接近1表示越相似。

tags

Object

自定义的标签名称和标签内容。

状态码： 400

表7 响应Body参数

参数

参数类型

描述

error_code

String

调用失败时的错误码，具体请参见错误码。

调用成功时无此字段。

error_msg

String

调用失败时的错误信息。

调用成功时无此字段。

请求示例

  • 方式一：使用图片的BASE64编码，从图片索引库中搜索相似图片，返回被检索图像的数量为10。 
    POST https://{endpoint}/v1/{project_id}/{instance_name}/image/search

{
  "limit" : 10,
  "offset" : 0,
  "file" : "/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAAgABwESAAMAAAABAAEAAAEaAAUAAAABAAAAYgEbAAUAAAABAAAA..."
}
  • 方式二：使用图片的url，从图片索引库中搜索相似图片，返回被检索图像的数量为10。 
    POST https://{endpoint}/v1/{project_id}/{instance_name}/image/search

{
  "limit" : 10,
  "offset" : 0,
  "path" : "https://BucketName.obs.myhuaweicloud.com/image/test1.jpg"
}
  • 方式三：使用标签，从图片索引库中搜索相似图片，返回被检索图像的数量为10 
    POST https://{endpoint}/v1/{project_id}/{instance_name}/image/search

{
  "limit" : 10,
  "offset" : 0,
  "tags" : {
    "test-tags" : "test-image"
  }
}
  • 方式四：使用图片的BASE64编码和标签，从图片索引库中搜索相似图片，返回被检索图像的数量为10。 
    POST https://{endpoint}/v1/{project_id}/{instance_name}/image/search

{
  "limit" : 10,
  "offset" : 0,
  "file" : "/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAAgABwESAAMAAAABAAEAAAEaAAUAAAABAAAAYgEbAAUAAAABAAAA...",
  "tags" : {
    "test-tags" : "test-image"
  }
}
  • 方式五：使用图片URL和标签，从图片索引库中搜索相似图片，返回被检索图像的数量为10。 
    POST https://{endpoint}/v1/{project_id}/{instance_name}/image/search

{
  "limit" : 10,
  "offset" : 0,
  "path" : "https://BucketName.obs.myhuaweicloud.com/image/test1.jpg",
  "tags" : {
    "test-tags" : "test-image"
  }
}
  • 方式六：使用指定区域进行搜索，从图片索引库中搜索相似图片，返回被检索图像的数量为10。 
    POST https://{endpoint}/v1/{project_id}/{instance_name}/image/search

{
  "limit" : 10,
  "offset" : 0,
  "path" : "https://BucketName.obs.myhuaweicloud.com/image/test1.jpg",
  "box" : {
    "x" : 100,
    "y" : 200,
    "height" : 50,
    "width" : 20
  }
}

响应示例

状态码： 200

成功响应示例

{
  "count" : 2,
  "result" : [ {
    "path" : "https://BucketName.obs.myhuaweicloud.com/CBL025106G/CBL025106G_2.JPG",
    "sim" : 0.51263,
    "tags" : {
      "test-tags" : "test-image"
    }
  } ]
}

状态码： 400

失败响应示例

{
  "error_code" : "IS.0003",
  "error_msg" : "Arguments of path can not be null."
}

状态码

状态码

描述

200

成功响应示例。

400

失败响应示例。

错误码

请参见错误码。

父主题： API