智能多媒体 API

  • 以图搜图

    最近更新时间:2018-10-17 17:36:58

    七牛以图搜图服务可对一张图片在底库中进行相似图片搜索,结果返回与搜索图语义最相似的多张图片。整个服务由多个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 和 SuccessKey 生成鉴权,以便进行身份验证。<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 和 SuccessKey 生成鉴权,以便进行身份验证。<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 和 SuccessKey 生成鉴权,以便进行身份验证。<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 和 SuccessKey 生成鉴权,以便进行身份验证。<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 和 SuccessKey 生成鉴权,以便进行身份验证。<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 和 SuccessKey 生成鉴权,以便进行身份验证。<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 和 SuccessKey 生成鉴权,以便进行身份验证。<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 和 SuccessKey 生成鉴权,以便进行身份验证。<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 和 SuccessKey 生成鉴权,以便进行身份验证。<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 和 SuccessKey 生成鉴权,以便进行身份验证。<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
            }
        ]
    }
    
    

    文件适用规格


    可处理的图片文件:

    1. 图片大小不超过10M
    2. 图片尺寸不小于30x30,不超过4999x4999
    3. RGB通道数为3和3以内的图片,不能包含alpha通道
    4. 图片格式支持 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 元

    以上内容是否对您有帮助?
  • Icon free helper
    Close