Image Recognition/Matching API Documentation

API Summery :

Image Recognition/Matching API provides a service to find a match image in a client's image set for an input image. Image finger print characteristics such as color distribution, shape geometry, and image features are used for matching. Thank to our advanced image matching technology, our service has a great ability to resist noise of input image such as scaling, lighting change, rotating, and interference of background. Image Recognition/Matching API is a great service for applications of online shopping websites, ecommerce mobile Apps for offline & online interactions thus to bring offline shoppers to online for more transactions.


Image Recognition/Matching Features:

Great ability to resist input image noise, great for mobile Apps Capable to resist noise of input image such as scaling, lighting change, rotating, and interference of background
Picture-in-picture partial matching Capable to find a partial match even if the content of an input image is only part of an image in the image set
Dynamically adding & deleting items You can add, modify, and delete your image and related meta data dynamically. Searchable immediately after successful adding
Meta data You can add additional meta data such as product title, description, customized categories, any labels, all those are searchable by API
Image + keywords hybrid search Allow to combine visual search and keywords search, known as hybrid search to more accurately search what users want
Filtering result by customized category Allow to do visual search using filtering customized categories
Filtering result by customized labels Allow to do visual search using filtering by customized labels

Application scene :

image database trading platform, picture material website, picture community website, picture sharing APP



API end point : http://apipnp20.wozhitu.com:8086/vsearchtech/api/v1.0/apipnp_search

Image format requirement: JPG format 300 – 800 pix

Http method : POST

Request Parameters:(body) :

Parameter Name Type Required Parameter Location Description Default Value
apikey string Yes header API Key None
catid No No header Category ID (1 – 3000 integer) 0 (means all categories)
lang string No header Language: zh - Chinese; en - English zh - Chinese
fmt string No header Response format: json or xml json
subject int No header input keywords, used for image + keywords hybrid search None
labeland string No header AND logic labels for input image, positive integer,Example:65,58,408 None
labelor string No header OR logic labels for input image,positive integer,Example:305,38,5 None
labelnot string No header NOT logic labels for input image,positive integer,Example:345,368,45 None
p string No body The pth page shows the pth page, p is greater than or equal to 1 positive integer 1
numperpage string No body Show how many pages per page, should be a positive integer 16
maxitems string No body A total of how many show a total show, should be a positive integer 200

Request Parameters(body) :

Parameter Name Type Required Parameter Location Description Default Value
photo file Yes body Image for uploading None


Detailed use of tutorials


JSON Response Example:

{ resultList": [ { "class":"vs.vscommon.ImageSearchResultEntry", "imgName":"1392125321.jpg", "imgRelativePath":"0_All/41_xyz/0_All_Categories/227_e2/1392125321.jpg", "imgUrl":"http://www.xyz.cn/images/front/v/pic2/e2/04/1392125321.jpg", "info":null, "keyword":"Study,Signature", "productPageUrl":"http://www.xyz.cn/r/photo/view/id/1392125321/", "score":0.9785203, "tagsList":null, "title":"Gold pen signing contract" }, { "class":"vs.vscommon.ImageSearchResultEntry", "imgName":"1204325791.jpg", "imgRelativePath":"0_All/41_xyz/0_All_Categories/53_34/1204325791.jpg", "imgUrl":"http://www.xyz.cn/images/front/v/pic2/34/ce/1204325791.jpg", "info":null, "keyword":"white,animal,local", "productPageUrl":"http://www.xyz.cn/r/photo/view/id/1204325791/", "score":0.978022, "tagsList":null, "title":"Small fish in glass of water isolated"} ] }



API end point: http://apipnp20.wozhitu.com:8086/vsearchtech/api/v1.0/apipnp_search

Image format requirement: JPG format 300 – 800 pix

Http method : POST

Request Parameters(body) :

Parameter Name Type Required Parameter Location Description Default Value
apikey string Yes header API Key None
imgurl string Yes header Image URL None
catid No No header Category ID (1 – 3000 integer) 0 (means all categories)
lang string No header Language: zh - Chinese; en - English zh - Chinese
fmt string No header Response format: json or xml json
subject int No header input keywords, used for image + keywords hybrid search None
labeland string No header AND logic labels for input image, positive integer,Example:65,58,408 None
labelor string No header OR logic labels for input image,positive integer,Example:305,38,5 None
labelnot string No header NOT logic labels for input image,positive integer,Example:345,368,45 None
p string No body The pth page shows the pth page, p is greater than or equal to 1 positive integer 1
numperpage string No body Show how many pages per page, should be a positive integer 16
maxitems string No body A total of how many show a total show, should be a positive integer 200




JSON返回示例 :

{ resultList":[{"class":"vs.vscommon.ImageSearchResultEntry","imgName":"1392125321.jpg", "imgRelativePath":"0_All/41_xyz/0_All_Categories/227_e2/1392125321.jpg","imgUrl": "http://www.xyz.cn/images/front/v/pic2/e2/04/1392125321.jpg","info":null,"keyword": "Study,Signature","productPageUrl":"http://www.xyz.cn/r/photo/view/id/1392125321/", "score":0.9785203,"tagsList":null,"title":"Gold pen signing contract"},{"class": "vs.vscommon.ImageSearchResultEntry","imgName":"1204325791.jpg","imgRelativePath": "0_All/41_xyz/0_All_Categories/53_34/1204325791.jpg", "imgUrl":"http://www.xyz.cn/images/front/v/pic2/34/ce/1204325791.jpg", "info":null,"keyword":"white,animal, local","productPageUrl": "http://www.xyz.cn/r/photo/view/id/1204325791/","score":0.978022, "tagsList":null,"title":"Small fish in glass of water isolated"} ]}



API end point : http://apipnp20.wozhitu.com:8086/vsearchtech/api/v1.0/apipnp_additem

Image format requirement: JPG format 300 – 1200 pix

Http method : POST

Request Parameters(body) :

Parameter Name Type Required Parameter Location Description Default Value
apikey string Yes header API Key None
imgname string Yes header Image name, must be unique.
Example 123.jpg
None
catid int No header Category ID (1 – 3000 integer) None
lang String No header Language: zh - Chinese;en - English zh - Chinese
fmt String No header Response format: json or xml json
kwds String No header input keywords, used for image + keywords hybrid search. None
labels String No header Image labels, positive integer,separated by comma.Example: 65,58,408 None
title String No header Image title, example: dog on grass None
info String No header You can put image related meta data here. Will be returned back in search result response. None

Parameter Name Type Required Parameter Location Description Default Value
photo file Yes body Image for uploading None


Detailed use of tutorials

API end point : http://apipnp20.wozhitu.com:8086/vsearchtech/api/v1.0/apipnp_additem

Image format requirement: JPG format 300 – 1200 pix

Http method : POST

Request Parameters(body) :

Parameter Name Type Required Parameter Location Description Default Value
apikey string Yes header API Key None
imgname string Yes header Image name, must be unique.
Example 123.jpg
None
imgurl string Yes header Image URL None
catid int No header Category ID (1 – 3000 integer) None
lang String No header Language: zh - Chinese;en - English zh - Chinese
fmt String No header Response format: json or xml json
kwds String No header input keywords, used for image + keywords hybrid search. None
labels String No header Image labels, positive integer,separated by comma.Example: 65,58,408 None
title String No header Image title, example: dog on grass None
info String No header You can put image related meta data here. Will be returned back in search result response. None


API end point : http://apipnp20.wozhitu.com:8086/vsearchtech/api/v1.0/apipnp_deleteitem

Http method: POST

Request Parameters(body) :

Parameter Name Type Required Parameter Location Description Default Value
apikey string Yes header API Key None
imgname string Yes header Image name, must be unique.Example 123.jpg None
fmt string Yes header Response format: json or xml json


API end point : http://apipnp20.wozhitu.com:8086/vsearchtech/api/v1.0/apipnp_detail

Http method : POST or GET

Request Parameters(body/header) :

Parameter Name Type Required Parameter Location Description Default Value
apikey string Yes header API Key None
imgname string Yes header Image name, must be unique.Example 123.jpg None
fmt string Yes header Response format: json or xml json


API end point :http://apipnp20.wozhitu.com:8086/vsearchtech/api/v1.0/apipnp_browse

Image format requirement: JPG format 300 – 800 pix

Http method : POST or GET

Request Parameters(body/header) :

Parameter Name Type Required Parameter Location Description Default Value
apikey string Yes header API Key None
catid No No header Category ID (1 – 3000 integer) 0 (means all categories)
lang string No header Language: zh - Chinese; en - English zh - Chinese
fmt string No header Response format: json or xml json
subject int No header input keywords, used for image + keywords hybrid search None
labeland string No header AND logic labels for input image, positive integer,Example:65,58,408 None
labelor string No header OR logic labels for input image,positive integer,Example:305,38,5 None
labelnot string No header NOT logic labels for input image,positive integer,Example:345,368,45 None
p string body/header 流览显示第p页面, p 为大于或等于1正整数 1
numperpage string body/header 每页流览显示多少个, 应为正整数 16
maxitems string body/header 最多一共流览显示多少个, 应为正整数 200



JSON Response Example :

{ resultList":[{"class":"vs.vscommon.ImageSearchResultEntry","imgName":"1392125321.jpg", "imgRelativePath":"0_All/41_xyz/0_All_Categories/227_e2/1392125321.jpg","imgUrl": "http://www.xyz.cn/images/front/v/pic2/e2/04/1392125321.jpg","info":null,"keyword": "Study,Signature","productPageUrl":"http://www.xyz.cn/r/photo/view/id/1392125321/", "score":0.9785203,"tagsList":null,"title":"Gold pen signing contract"},{"class": "vs.vscommon.ImageSearchResultEntry","imgName":"1204325791.jpg","imgRelativePath": "0_All/41_xyz/0_All_Categories/53_34/1204325791.jpg", "imgUrl":"http://www.xyz.cn/images/front/v/pic2/34/ce/1204325791.jpg", "info":null,"keyword":"white,animal, local","productPageUrl": "http://www.xyz.cn/r/photo/view/id/1204325791/","score":0.978022, "tagsList":null,"title":"Small fish in glass of water isolated"} ]}



Download Java resources
Download Python resources
Download Php resources

Error Code Reference:


Error Codes Related to Access Control:
API_CODE_ERROR_exceeded_access_total Exceeded API access limit in total
API_CODE_ERROR_exceeded_access_frequency Exceeded API access frequency limit
API_CODE_ERROR_exceeded_access_frequency_min Exceeded API access limit per minute
API_CODE_ERROR_exceeded_access_frequency_hr Exceeded API access limit per hour
API_CODE_ERROR_exceeded_access_frequency_day Exceeded API access limit per day
API_CODE_ERROR_exceeded_access_frequency_month xceeded API access limit per month
API_CODE_ERROR_two_API_calls_time_too_close Two API calls are too close in time
IMAGE_INDEX_CODE_ERROR_IMAGE_EXCEED_MAX_DOCS_PER_UID Exceeded max number of images in index per user
API_CODE_ERROR_not_allow_write_index Pause in adding image to index (server might be in maintain service, please wait )

Error Codes Related to Wrong Parameters:
API_CODE_ERROR_invalid_apikey Invalid apikey
IMAGE_INDEX_ITEM_CODE_ERROR_INVALID_imgName Invalid image name
IMAGE_INDEX_ITEM_CODE_ERROR_INVALID_imgUrl Invalid image URL
IMAGE_INDEX_ITEM_CODE_ERROR_INVALID_catid_must_be_1_to_3000 Invalid image category (Must be 1-3000 Integer)
IMAGE_INDEX_ITEM_CODE_ERROR_INVALID_labels_must_be_positive_integer Invalid label(Must be positive integer)
IMAGE_INDEX_ITEM_CODE_ERROR_INVALID_FIELDS_any_field_must_not_have_double_quote Invalid image data, must not have double quote
IMAGE_INDEX_ITEM_CODE_ERROR_INVALID_LANG Invalid language parameter(must be zh for Chinese or en for English)
IMAGE_INDEX_CODE_ERROR_DOWNLOAD_IMAGE Error in downloading image, please check provided image URL
IMAGE_INDEX_CODE_ERROR_IMAGE_SIZE_TOO_BIG Image size is too big(image must be 400 – 800PIX JPG format)
IMAGE_INDEX_DELETE_IMG_CODE_ERROR_NOT_FOUND_ITEM Error in deleting, image not found