智能多媒体服务 > API 文档 > 以图搜图（即将下线）

以图搜图（即将下线）

最近更新时间: 2021-12-22 16:38:46

七牛以图搜图服务可对一张图片在底库中进行相似图片搜索，结果返回与搜索图语义最相似的多张图片。整个服务由多个API接口组合而成，可实现功能包括新建图像库、删除图像库、添加或者删除图片、显示所有或指定图像库信息、显示所有或指定图片信息以及图片搜索。

组合接口描述

接口名称	请求路径	请求方式	接口功能
新建图像库	/v1/image/group/<group_id>/new	POST	创建一个新的图像库并将图片信息存入库中，返回录入图片的唯一标识
删除图像库	/v1/image/group/<group_id>/remove	POST	删除指定的图像库，如果图像库中含有图片也一并删除
添加图片	/v1/image/group/<group_id>/add	POST	在指定图像库中添加图片，返回新添加的图片唯一标识
删除图片	/v1/image/group/<group_id>/delete	POST	删除指定图像库中的一张或多张图片
显示所有图像库	/v1/image/group	GET	显示所有创建的图像库的唯一 id
显示指定图像库信息	/v1/image/group/<group_id>/info	GET	显示指定图像库中图片个数
显示所有图片	/v1/image/group/<group_id>?marker=<marker>&limit=<limit>	GET	显示指定的图像库中的所有图片
显示指定图片信息	/v1/image/group/<group_id>/image	POST	显示某图像库中指定一张图片信息
图片搜索	/v1/image/groups/search	POST	图像库搜索。在指定的图像库中，返回与待搜索图片最相似的多张图片注意：支持在多个库进行搜索
图片搜索（旧版本）	/v1/image/group/<group_id>/search	POST	图像库搜索。在指定的图像库中，返回与待搜索图片最相似的多张图片注意：不支持多库搜索，此接口用于给在2018年9月1日之前接入的用户进行对照查看，请新用户统一使用上一行新图片搜索接口

具体调用方式及示例

新建图像库

创建一个新的图像库并将图片信息存入库中，返回录入图片的唯一标识。
注意: 每个图像库最多存入50万张图片。

请求方式：POST
请求url: http://ai.qiniuapi.com/v1/image/group/<group_id>/new

Header

字段	取值
Content-Type	application/json
Authorization	Qiniu <AccessKey>:<Sign> 注意: 用户请根据 AccessKey 和 SecretKey 生成鉴权，以便进行身份验证。<Sign> 的取值请参考七牛鉴权

请求字段说明

字段	取值	是否必选	说明
group_id	string	Y	图像库的唯一标识
uri	string	Y	图片资源。支持两种资源表达方式： 1. 网络图片URL地址； 2. 图片 base64 编码字符串，需在编码字符串前加上前缀 `data:application/octet-stream;base64,` 例：`data:application/octet-stream;base64,xxx`
attribute.id	string	N	自定义图片 id，在返回结果中显示，如果该字段为空，则会随机生成一个 id 并返回
attribute.label	string	N	图片标签
attribute.desc	map	N	图片的备注信息,内容可以是布尔值、数字、字符串、数组或 json，最大允许长度为4096字节

请求语法

POST /v1/image/group/<group_id>/new  Http/1.1
Content-Type: application/json
Authorization: Qiniu <AccessKey>:<Sign>

{
	"data": [
		{
			"uri": "http://xx.com/xxx",
			"attribute": {
				"id": <id>,
				"label": <label>,
				"desc": <additional information>
			}
		},
		{
			"uri": "http://xx.com/xxx",
			"attribute": {
				"id": <id>,
				"label": <label>,
				"desc": <additional information>
			}
		}
	]
}

返回字段说明

字段	取值	说明
images	list	录入的所有图片id列表，若某张图片入库失败，则为空
errors	list	录入的所有图片的错误信息，若某张图片入库成功，则为`null`
errors.code	int	错误码
errors.message	string	错误描述信息

返回示例

{
    "errors": [
        null, 
        null, 
        null, 
        null
    ], 
    "images": [
        "1", 
        "2", 
        "3", 
        "4"
    ]
}

删除图像库

删除指定的图像库，如果图像库中含有图片也一并删除。

请求方式：POST
请求url: http://ai.qiniuapi.com/v1/image/group/<group_id>/remove

Header

字段	取值
Authorization	Qiniu <AccessKey>:<Sign> 注意: 用户请根据 AccessKey 和 SecretKey 生成鉴权，以便进行身份验证。<Sign> 的取值请参考七牛鉴权

请求字段说明

字段	取值	是否必选	说明
group_id	string	Y	图像库的唯一标识

** 注意：** 请求 body 为空。

请求语法

POST /v1/image/group/<group_id>/remove  Http/1.1
Authorization: Qiniu <AccessKey>:<Sign>

返回示例

200 ok

{}

** 注意：** 删除成功返回内容为空。

添加图片

在指定图像库中添加图片，返回新添加的图片唯一标识。

请求方式：POST
请求url: http://ai.qiniuapi.com/v1/image/group/<group_id>/add

Header

字段	取值
Content-Type	application/json
Authorization	Qiniu <AccessKey>:<Sign> 注意: 用户请根据 AccessKey 和 SecretKey 生成鉴权，以便进行身份验证。<Sign> 的取值请参考七牛鉴权

请求字段说明

字段	取值	是否必选	说明
group_id	string	Y	图像库的唯一标识
uri	string	Y	图片资源。支持两种资源表达方式： 1. 网络图片URL地址； 2. 图片 base64 编码字符串，需在编码字符串前加上前缀 `data:application/octet-stream;base64,` 例：`data:application/octet-stream;base64,xxx`
attribute.id	string	N	自定义图片 id，在返回结果中显示，如果该字段为空，则会随机生成一个 id 并返回
attribute.label	string	N	图片标签
attribute.desc	map	N	图片的备注信息。内容可以是布尔值、数字、字符串、数组或 json，最大允许长度为4096字节

请求语法

POST /v1/image/group/<group_id>/add  Http/1.1
Content-Type: application/json
Authorization: Qiniu <AccessKey>:<Sign>

{
	"data": [
		{
			"uri": "http://xx.com/xxx",
			"attribute": {
				"id": <id>,
				"label": <label>,
				"desc": <additional information>
			}
		},
		{
			"uri": "http://xx.com/xxx",
			"attribute": {
				"id": <id>,
				"label": <label>,
				"desc": <additional information>
			}
		}
	]
}

返回字段说明

字段	取值	说明
images	list	录入的所有图片id列表，若某张图片入库失败，则为空
errors	list	录入的所有图片的错误信息，若某张图片入库成功，则为`null`
errors.code	int	错误码
errors.message	string	错误描述信息

返回示例

{
    "errors": [
        null
    ], 
    "images": [
        "5"
    ]
}

删除图片

删除指定图像库中一张或多张图片。

请求方式：POST
请求url: http://ai.qiniuapi.com/v1/image/group/<group_id>/delete

Header

字段	取值
Content-Type	application/json
Authorization	Qiniu <AccessKey>:<Sign> 注意: 用户请根据 AccessKey 和 SecretKey 生成鉴权，以便进行身份验证。<Sign> 的取值请参考七牛鉴权

请求字段说明

字段	取值	是否必选	说明
group_id	string	Y	图像库的唯一标识
image_id	string	Y	图片唯一标识

请求语法

POST /v1/image/group/<group_id>/delete  Http/1.1
Content-Type: application/json
Authorization: Qiniu <AccessKey>:<Sign>

{
	"images":[
		<image_id>,
		...
	]
}

返回语法

200 ok

{}

** 注意：** 删除成功返回内容为空。

显示所有图像库

显示所有已建立的图像库的唯一id。

请求方式：GET
请求url: http://ai.qiniuapi.com/v1/image/group

Header

字段	取值
Authorization	Qiniu <AccessKey>:<Sign> 注意: 用户请根据 AccessKey 和 SecretKey 生成鉴权，以便进行身份验证。<Sign> 的取值请参考七牛鉴权

请求语法

GET /v1/image/group  Http/1.1
Authorization: Qiniu <AccessKey>:<Sign>

返回字段说明

字段	取值	说明
code	int	处理状态：`0`表示调用成功
message	string	与`code`对应的状态描述信息
result	list	图像库 id 列表

返回示例

{
    "code": 0, 
    "message": "", 
    "result": [
        "1",
		"2"
    ]
}

显示指定图像库信息

显示指定图像库中图片个数。

请求方式：GET
请求url: http://ai.qiniuapi.com/v1/image/group/<group_id>/info

Header

字段	取值
Authorization	Qiniu <AccessKey>:<Sign> 注意: 用户请根据 AccessKey 和 SecretKey 生成鉴权，以便进行身份验证。<Sign> 的取值请参考七牛鉴权

请求字段说明

字段	取值	是否必选	说明
group_id	string	Y	图像库的唯一标识

请求语法

GET /v1/image/group/<group_id>/info  Http/1.1
Authorization: Qiniu <AccessKey>:<Sign>

返回字段说明

字段	取值	说明
count	int	指定图像库中图片个数

返回示例

{
	"count": 4
}

## 显示所有图片显示指定的图像库中的所有图片。

请求方式：GET
请求url: http://ai.qiniuapi.com/v1/image/group/<group_id>?marker=<marker>&limit=<limit>

Header

字段	取值
Authorization	Qiniu <AccessKey>:<Sign> 注意: 用户请根据 AccessKey 和 SecretKey 生成鉴权，以便进行身份验证。<Sign> 的取值请参考七牛鉴权

请求字段说明

字段	取值	是否必选	说明
group_id	string	Y	图像库的唯一标识
marker	string	N	上一次请求返回的标记，作为本次请求的起点信息，默认值为空字符串
limit	int	N	返回数量，范围为 1-1000，默认值为 1000

注意： 如果请求时不需要设置marker或者limit，则请求url中不加此参数，例如：http://ai.qiniuapi.com/v1/image/group/<group_id>或http://ai.qiniuapi.com/v1/image/group/<group_id>?limit=<limit>

请求语法

GET /v1/image/group/<group_id>?marker=<marker>&limit=<limit>  Http/1.1
Authorization: Qiniu <AccessKey>:<Sign>

返回字段说明

字段	取值	说明
code	int	处理状态：`0`表示调用成功
message	string	与`code`对应的状态描述信息
marker	string	本次请求的标记信息，可作为下一次请求的参数传入，如果没有剩余条目则返回空字符串
id	string	生成的该图片的唯一标识
value.label	string	图片标签
value.desc	map	图片入库时的备注信息

返回示例

{
    "code": 0, 
    "marker": "", 
    "message": "", 
    "result": [
        {
            "id": "1", 
            "value": {
                "desc": "", 
                "label": "shoes"
            }
        }, 
        {
            "id": "2", 
            "value": {
                "desc": "", 
                "label": "shoes"
            }
        }
    ]
}

显示指定图片信息

显示某图像库中指定一张图片信息。

请求方式：POST
请求url: http://ai.qiniuapi.com/v1/image/group/<group_id>/image

Header

字段	取值
Content-Type	application/json
Authorization	Qiniu <AccessKey>:<Sign> 注意: 用户请根据 AccessKey 和 SecretKey 生成鉴权，以便进行身份验证。<Sign> 的取值请参考七牛鉴权

请求字段说明

字段	取值	是否必选	说明
group_id	string	Y	图像库的唯一标识
id	string	Y	图片的唯一标识

请求语法

POST /v1/image/group/<group_id>/image  Http/1.1
Content-Type: application/json
Authorization: Qiniu <AccessKey>:<Sign>

{
	"id": "xxx"
}

返回字段说明

字段	取值	说明
label	string	图片标签
desc	map	图片入库时的备注信息

返回示例

{
    "desc": "", 
    "label": "bag"
}

图片搜索

相似图片搜索。在指定的图像库中，返回与待搜索图片最相似的多张图片。支持在多个库搜索

注意： 支持在多个库内进行搜索，最多2个。

请求方式：POST
请求url: http://ai.qiniuapi.com/v1/image/groups/search

Header

字段	取值
Content-Type	application/json
Authorization	Qiniu <AccessKey>:<Sign> 注意: 用户请根据 AccessKey 和 SecretKey 生成鉴权，以便进行身份验证。<Sign> 的取值请参考七牛鉴权

请求字段说明

字段	取值	是否必选	说明
uri	string	Y	图片资源。支持两种资源表达方式： 1. 网络图片URL地址； 2. 图片 base64 编码字符串，需在编码字符串前加上前缀 `data:application/octet-stream;base64,` 例：`data:application/octet-stream;base64,xxx`
params.groups	list	Y	搜索的图像库列表，最多2个
params.groups.[]	string	Y	图像库id
params.limit	int	N	匹配图片TOPN，默认为1，最大允许10000。若为-1，则返回所有匹配图片
params.threshold	float	N	匹配图片的精度阈值，默认使用系统设置值。若该值小于系统设置值，则仍使用系统设置值

请求语法

POST /v1/image/groups/search Http/1.1
Content-Type: application/json
Authorization: Qiniu <AccessKey>:<Sign>

{
	"data": {
		"uri": "http://xx.com/xxx"
	},
	"params": {
		"groups": [
			<group_id>
		],
		"limit": 5,
		"threshold": 0.85
	}
}

返回字段说明

字段	取值	说明
code	int	处理状态：`0`表示调用成功
message	string	与`code`对应的状态描述信息
result	list	检索得到的图片列表
id	string	检索得到的图片id
label	string	检索得到的图片标签
score	float	0~1,检索结果的可信度，1为确定
group	string	检索得到的图片所属的图像库id
desc	map	图片入库时的备注信息

返回示例

{
    "code": 0, 
    "message": "", 
    "result": [
        {
            "desc": "",
            "group": "1", 
            "id": "1", 
            "label": "shoes", 
            "score": 0.6127953
        }, 
        {
            "desc": "", 
            "group": "1", 
            "id": "2", 
            "label": "shoes", 
            "score": 0.60273343
        }
    ]
}

图片搜索（旧版本）

图片搜索。在指定的图像库中，返回与待搜索图片最相似的多张图片
注意： 不支持多库搜索，此接口用于给在2018年9月1日之前接入的用户进行对照查看，请新用户统一使用上一行新图片搜索接口

请求方式：POST
请求url: http://ai.qiniuapi.com/v1/image/group/<group_id>/search

Header

字段	取值
Content-Type	application/json
Authorization	Qiniu <AccessKey>:<Sign> 注意: 用户请根据 AccessKey 和 SecretKey 生成鉴权，以便进行身份验证。<Sign> 的取值请参考七牛鉴权

请求字段说明

字段	取值	是否必选	说明
group_id	string	Y	图像库的唯一标识
uri	string	Y	图片资源。支持两种资源表达方式： 1. 网络图片URL地址； 2. 图片 base64 编码字符串，需在编码字符串前加上前缀 `data:application/octet-stream;base64,` 例：`data:application/octet-stream;base64,xxx`
params.limit	int	N	匹配图片TOPN，默认为1，最大允许10000。若为-1，则返回所有匹配图片

请求语法

POST /v1/image/group/<group_id>/search Http/1.1
Content-Type: application/json
Authorization: Qiniu <AccessKey>:<Sign>

{
	"data": {
		"uri": "http://xx.com/xxx"
	},
	"params": {
		"limit": 1
	}
}

返回字段说明

字段	取值	说明
code	int	处理状态：`0`表示调用成功
message	string	与`code`对应的状态描述信息
result	list	检索得到的图片列表
id	string	检索得到的图片id
label	string	检索得到的图片标签
score	float	0~1,检索结果的可信度，1为确定
desc	map	图片入库时的备注信息

返回示例

{
    "code": 0, 
    "message": "", 
    "result": [
        {
            "desc": "", 
            "id": "1", 
            "label": "shoes", 
            "score": 0.6127953
        }, 
        {
            "desc": "", 
            "id": "2", 
            "label": "shoes", 
            "score": 0.60273343
        }, 
        {
            "desc": "",  
            "id": "4", 
            "label": "dress", 
            "score": 0.42204335
        }
    ]
}

文件适用规格

可处理的图片文件：

图片大小不超过10M
图片尺寸不小于30x30，不超过4999x4999
RGB通道数为3和3以内的图片，不能包含alpha通道
图片格式支持 png、jpg、jpeg、bmp、webp 和 gif

服务价格

每月总调用量P	费用
单位：万张	单价（元/百张）
0 < P ≤ 500	0.38
500 < P ≤ 1500	0.36
1500 < P ≤ 3000	0.34
P > 3000	0.32

计费示例

某公司2018年5月使用七牛云以图搜图服务，共发起500万张请求，
则当月使用七牛云以图搜图服务产生的费用为：

确定的结果产生费用：0.38元/百张 * 500万张 = 19000 元

总计费用：19000 元

以上内容是否对您有帮助？