Visual Intelligence API
Deep Vision API is composed by the following main modules:
Visual Face
The model detects and recognizes faces in image and video content. It provides coordinate locations of the facial detection. In addition, the model can perform facial verification for target subjects and provides demographic information (age and gender of people). Our current library contains the ability to recognize 5,000+ celebrities and custom faces from customer’s private datasets that can easily be added to the model.
Visual Brand
This model identifies and provides coordinate locations of brand logos in image and video content. The model is able to detect brand logos in various forms. We can customize which brands to detect and new custom brands can be added to our models upon request.
Visual Context
This model identifies and predicts concepts in image and video content. The model supports over 13,000+ general concepts and can categorize image and video content. Additional tagged concepts can also be added to the model upon request. Visual Context allows for auto-categorization of products and objects, and provides conceptual context information for video and images content.
Visual Search
This model identifies objects in image and video content and provides the ability to visually search for a target object. The model will return exact object matches as well as visually similar objects including similarity scores against the target object. Our API can easily integrate with customer’s product inventories or object galleries.
Visual Vehicle
Visual Vehicle Model is a piece of the broader Deep Vision Visual Intelligence API which provides image and video recognition applied to many industries. Visual Vehicle identifies the year, make, and model (YMM) of vehicles in image content from any angle. It can also provide the angle of the vehicle view, we support: front right, front left, front center, rear right, rear left, rear center, side left, side right. Our current library contains the ability to recognize 3,000+ YMM (all vehicles of the past 10 years in the US and LATAM) and new vehicles can be added to the system under request.
Authentication
How to get access?
To get your access token and start using the API, please contact us. Once you get your access token, you can quickly start sending requests to Visual Intelligence API.
Predict
With Predict, you can understand your images and videos and get the most value out of them. Using our API is very easy and straightforward. You can get predictions using "predict" request and by selecting different services you can choose between all the functionalities we currently support. Start predicting is fairly easy, you must provide the image URL or a base64 encoded image you want to analyze plus the name of the service you want to use (Face, Brand, or Context).
Predict with Visual Context
To get contextual information about your data you need to call "predict" with the image URL or a base64 encoded image and the name of the service "context". Inside context you can choose between different modes, although only "default" mode is supported at this time. As a response you'll get concept tags organized into three categories: "humanlike" meaning labels a human would use to naturally describe what he’s seeing; “related-tags” which are semantically and contextually closely related to the visual content in the image; and “extra” tags which might be relevant to the concept but not necessarily to the actual visual content. Note: “extra” tags are currently not supported.
Request with image url
curl -X POST \
-H "Api-Key: <token>" \
-H "Content-Type: application/json" \
-d '
{
"image":"http://img.deepvisionai.com//visualintelligence/documentation/example.jpg",
"context":{
"modes":"default"
}
}' \
http://api.visualintelligence.deepvisionai.com/predict
request with base64 encoded image
(echo '
{
"image":"data:image/jpeg;base64,'$(base64 -w 0 /path/to/image/name.jpg)'",
"context":{
"modes":"default"
}
}') | curl -X POST \
-H "Api-Key: <token>" \
-H "Content-Type: application/json" \
-d @- \
http://api.visualintelligence.deepvisionai.com/predict
response
{
"context": [
{
"humanlike": [
{
"score": 0.3234557807,
"tag": "person"
}
],
"related": [
{
"tag": "material wealth"
},
{
"tag": "great"
},
{
"tag": "human"
}
],
"extra": []
},
{
"humanlike": [
{
"score": 0.2285063267,
"tag": "bow tie"
}
],
"related": [
{
"tag": "black bow"
}
],
"extra": []
},
{
"humanlike": [
{
"score": 0.0699283034,
"tag": "evening dress"
}
],
"related": [
{
"tag": "semiformal evening"
}
],
"extra": []
},
...
]
}
Predict with Visual Vehicle
If you received your API Key, you can start making calls to the API. To send an image to the API you can use public URLs or Base64 encoded images. Visual Vehicle has three “modes” of operation:
- “detection” to detect a vehicle in the image
- “views” to get vehicle view
- “mmy_us” to get YMM classification
- To enable all modes you need to set “mmy_us | views | detection”
Below are code examples of how you would send the images and receive back JSON results.
Request with image url
curl -X POST \
-H "Api-Key: <token>" \
-H "Content-Type: application/json" \
-d '
{
"image": "http://img.deepvisionai.com//visualintelligence/documentation/car_example.jpg",
"vehicle": {
"modes":"mmy_us|view|detect"
}
}' \
http://api.visualintelligence.deepvisionai.com/predict
request with base64 encoded image
(echo '
{
"image":"data:image/jpeg;base64,'$(base64 -w 0 /path/to/image/name.jpg)'",
"vehicle": {
"modes":"mmy_us|view|detect"
}
}') | curl -X POST \
-H "Api-Key: <token>" \
-H "Content-Type: application/json" \
-d @- \
http://api.visualintelligence.deepvisionai.com/predict
response
{
"vehicle": [
{
"View": {
"view": Front Left View,
"score": 0.68,
},
"bbox": {
"right": 610,
"left": 47,
"bottom": 384,
"top": 72
},
"mmy": {
"make": "Ford Focus",
"model": "2015-2016",
"score": 0.75
}
}
]
}
Predict with Visual Face
To detect faces in image and video content, recognize people and extract face demographics like age and gender you can call "predict" defining "face" service, plus the mode that allows you to select between the different options.
To start predicting face information you must provide the image URL or a base64 encoded image and set "face" as the service. With "modes" = "default" you will get a list of coordinate locations of the detected faces plus the associated detection score.
Please visit Visual Face section below to enable age, gender and recognition and to fully understand how this service works.
Predict with Visual Brand
With this module you will be able to detect brand logos in images and video content
REQUEST WITH IMAGE URL
curl -X POST \
-H "Api-Key: " \
-H "Content-Type: application/json" \
-d '
{
"image":"https://s3-us-west-2.amazonaws.com/dv-static-files/visualintelligence/sample-images/sample_brands_8.jpg",
"brand":{
"modes":"default"
}
}' \
http://api.visualintelligence.deepvisionai.com/predict
REQUEST WITH BASE64 ENCODED IMAGE
(echo '
{
"image":"data:image/jpeg;base64,'$(base64 -w 0 /path/to/image/name.jpg
)'",
"brand":{
"modes":"default"
}
}') | curl -X POST \
-H "Api-Key: " \
-H "Content-Type: application/json" \
-d @- \
http://api.visualintelligence.deepvisionai.com/predict
RESPONSE
{
"brand": [
{
"brand": {
"tag": "starbucks",
"score": 0.7686241269
},
"bbox": {
"top": 268,
"left": 295,
"right": 366,
"bottom": 410
}
},
{
"brand": {
"tag": "starbucks",
"score": 0.9234706759
},
"bbox": {
"top": 311,
"left": 438,
"right": 564,
"bottom": 436
}
},
{
"brand": {
"tag": "starbucks",
"score": 0.9301341176
},
"bbox": {
"top": 471,
"left": 109,
"right": 251,
"bottom": 580
}
}
]
}
Predict with multiple services
If you want, you can combine different services by specifying them on the same request.
Note: response times can be increased due to additional service calls.
Request
curl -X POST \
-H "Api-Key: <token>" \
-H "Content-Type: application/json" \
-d '
{
"image":"http://img.deepvisionai.com//visualintelligence/documentation/example.jpg",
"context": {
"modes": "default"
},
"face":{
"modes":"default"
}
}' \
http://api.visualintelligence.deepvisionai.com/predict
response
{
"context": [
{
"humanlike": [
{
"score": 0.3234557807,
"tag": "person"
}
],
"related": [
{
"tag": "material wealth"
},
{
"tag": "great"
},
{
"tag": "human"
}
],
"extra": []
},
{
"humanlike": [
{
"score": 0.2285063267,
"tag": "bow tie"
}
],
"related": [
{
"tag": "black bow"
}
],
"extra": []
},
{
"humanlike": [
{
"score": 0.0699283034,
"tag": "evening dress"
}
],
"related": [
{
"tag": "semiformal evening"
}
],
"extra": []
},
...
],
"face": [
{
"bbox": {
"right": 531,
"left": 315,
"top": 101,
"bottom": 303,
"score": 0.9107125998
}
},
{
"bbox": {
"right": 247,
"left": 70,
"top": 166,
"bottom": 331,
"score": 0.9068710208
}
}
]
}
Visual Face
With Visual Face you can perform facial detection, recognition and estimate age and gender in your own collection of images or any data you want to analyze. To start predicting face information you must provide the image URL or a base64 encoded image and set "face" as the service. The modes we support to execute each feature are listed below:
- Face detection: With "modes"="default" you will get a list of coordinate locations of the detected faces plus the associated detection score.
- Age estimation: With “modes”=”age” you’ll get the age of the detected persons.
- Gender estimation: With “modes”=”gender” you’ll get the gender of the detected persons.
- Face recognition: With “modes”=”recognition” you can recognize people in your own dataset of subjects. To do so, you need to add your subjects first. Please see Create Subject Dataset section to proceed.
Face Detection
To detect faces you must provide the image URL or a base64 encoded image and define "face" as the service with "modes"="default". You will get a list of coordinate locations of the detected faces plus the associated detection score.
Request with image url
curl -X POST \
-H "Api-Key: <token>" \
-H "Content-Type: application/json" \
-d '
{
"image":"http://img.deepvisionai.com//visualintelligence/documentation/example.jpg",
"face":{
"modes":"default"
}
}' \
http://api.visualintelligence.deepvisionai.com/predict
Request with base64 encoded image
curl -X POST \
-H "Api-Key: <token>" \
-H "Content-Type: application/json" \
-d '
{
"image":"data:image/jpeg;base64,$(base64 -w 0 /path/to/image/name.jpg)",
"face":{
"modes":"default"
}
}' \
http://api.visualintelligence.deepvisionai.com/predict
Response
{
"face": [
{
"bbox": {
"right": 531,
"left": 315,
"top": 101,
"bottom": 303,
"score": 0.9107125998
}
},
{
"bbox": {
"right": 247,
"left": 70,
"top": 166,
"bottom": 331,
"score": 0.9068710208
}
}
]
}
Face Demographics
To estimate age and gender you must provide the image URL or a base64 encoded image and define "face" as the service with "modes"="age", "modes"="gender" or both "modes"="age|gender". In the JSON response, you will get the estimated age and gender and their corresponding scores.
Request with image url
curl -X POST \
-H "Api-Key: <token>" \
-H "Content-Type: application/json" \
-d '
{
"image":"http://img.deepvisionai.com//visualintelligence/documentation/example.jpg",
"face":{
"modes":"age | gender"
}
}' \
http://api.visualintelligence.deepvisionai.com/predict
Response
{
"face": [
{
"bbox": {
"right": 529,
"left": 316,
"top": 100,
"bottom": 304,
"score": 0.9104
},
"age": {
"score": 0.561,
"tag": 35
},
"gender": {
"score": 0.88,
"tag": "male"
},
},
{
"bbox": {
"right": 248,
"left": 71,
"top": 167,
"bottom": 331,
"score": 0.9083
},
"age": {
"score": 0.6858,
"tag": 29
},
"gender": {
"score": 0.9534,
"tag": "female"
}
}
]
}
Face Recognition
To perform facial recognition, you must provide the image URL or a base64 encoded image and define "face" as the service with "modes"="recognize". In the JSON response, you will get name of the subject and the probability score. Our current library recognizes 5,000+ celebrities. The ID of the celebrities Dataset is cd2587d9-f9d1-47f8-a958-61c99effbecd. To add custom
faces to the model please see Create Subjects Dataset section.
Request with image url
curl -X POST \
-H "Api-Key: <token>" \
-H "Content-Type: application/json" \
-d '
{
"image":"http://img.deepvisionai.com//visualintelligence/documentation/example.jpg",
"face":{
"modes":"recognize",
"dataset_id":"cd2587d9-f9d1-47f8-a958-61c99effbecd",
}
}' \
http://api.visualintelligence.deepvisionai.com/predict
Response
{
"face": [
{
"bbox": {
"right": 529,
"left": 316,
"top": 100,
"bottom": 304,
"score": 0.9104
},
"recognize": [
{
"score": 0.2734,
"subject_name":"Brad Pitt",
"subject_id":"c7cd596d-60ee-476a-bd1c-bbca9e366b0c",
"dataset_id":"cd2587d9-f9d1-47f8-a958-61c99effbecd"
}
]
},
{
"bbox": {
"right": 248,
"left": 71,
"top": 167,
"bottom": 331,
"score": 0.9083
},
"recognize": {
"score": 0.2762,
"subject_name":"Angelina Jolie",
"subject_id":"d07cd7a9-66a4-47cc-9335-139f33754bde",
"dataset_id":"cd2587d9-f9d1-47f8-a958-61c99effbecd"
}
}
]
}
Create subject Dataset
Visual Face allows you to add your own collection of subjects you want to recognize and start recognizing them immediately. We suggest you to add 4-10 photos per subject to get optimal results. To do so, you will need to execute the following steps:
- Create an empty dataset
- Add a new subject to the dataset
- Add images to the given subject
- Use the predict method to perform face recognition
You can create a new and empty Dataset with the following request. You are allowed to create as many Datasets as you need. Once a new Dataset is created, you will get the Dataset ID as response.
Request
curl -X POST \
-H "Api-Key: <token>" \
-F dataset_name="Hollywood people" \
http://api.visualintelligence.deepvisionai.com/face/add_dataset
Endpoint: /face/add_dataset
Request parameters
| dataset_name | string (optional) Dataset name given by user. |
Response
{
"dataset_id": "e1744eac-3f8a-447c-96cc-8aae63b3d6f9",
"dataset_name": "Hollywood celebrities"
}
Create a new Subject
To add a new subject into your Dataset you must perform the following request.
Request
curl -X POST \
-H "Api-Key: <token>" \
-F dataset_id="e1744eac-3f8a-447c-96cc-8aae63b3d6f9" \
-F subject_name=”Leonardo DiCaprio” \
http://api.visualintelligence.deepvisionai.com/face/add_subject
Endpoint: /face/add_subject
Request parameters
| dataset_id | string (required) Dataset id to add the subject. |
| subject_name | string (optional) Subject name given by user. |
Response
{
"dataset_id": "e1744eac-3f8a-447c-96cc-8aae63b3d6f9",
"subject_id": "ec8c04a8-c4b0-481b-ab21-978845e730ed",
"subject_name": "Leonardo DiCaprio"
}
Add images to a Subject
You can add images to a given subject by performing the following request:
Request
curl -X POST \
-H "Api-Key: <token>" \
-F subject_id="ec8c04a8-c4b0-481b-ab21-978845e730ed" \
-F image=”https://goo.gl/iSfpMg” \
-F alias=”DiCaprio Photo 01” \
http://api.visualintelligence.deepvisionai.com/face/add_image
Endpoint: /face/add_image
Request parameters
| subject_id | string (required) Subject id to add the image. |
| image | file (required) Image URL, bytes or base64 encoded image. |
| alias | string (optional) Image alias name. |
Response
{
"image_id": "3d64c2e5-42a9-497e-8185-b87ad62c0be8",
"subject_id": "ec8c04a8-c4b0-481b-ab21-978845e730ed",
"alias": "DiCaprio Photo 01"
}
List images
To get the list of images contained in your subjects Dataset, please use the request below.
Request
curl -X POST \
-H "Api-Key: <token>" \
-F subject_id="ec8c04a8-c4b0-481b-ab21-978845e730ed" \
http://api.visualintelligence.deepvisionai.com/face/list_images
Endpoint: /face/list_images
Request parameters
| subject_id | string (required) Id of the Subject where we want to list images. |
Response
{
"results": [
{
"image_id": "3d64c2e5-42a9-497e-8185-b87ad62c0be8",
"image_alias": "DiCaprio Photo 1"
},
{
"image_id": "9b0f25df-8884-4708-84fa-c2bf701be1a2",
"image_alias": "DiCaprio Photo 2"
},
...
]
}
List Subjects
To get the list of subjects contained in your Dataset, please use the request below.
Request
curl -X POST \
-H "Api-Key: <token>" \
-F dataset_id="e1744eac-3f8a-447c-96cc-8aae63b3d6f9" \
http://api.visualintelligence.deepvisionai.com/face/list_subjects
Endpoint: /face/list_datasets
Request parameters
| subject_id | string (required) Id of the Dataset where we want to list subjects. |
Response
{
"results": [
{
"subject_id": "ec8c04a8-c4b0-481b-ab21-978845e730ed",
"subject_name": "Leonardo DiCaprio"
},
{
"subject_id": "c3bf43d9-d68c-4b8e-97b0-8f26b80f189e",
"subject_name": "Kate Winslet"
},
...
]
}
List Datasets
All collection of images (Datasets) can be listed by using this request.
Request
curl -X POST \
-H "Api-Key: <token>" \
http://api.visualintelligence.deepvisionai.com/face/list_datasets
Endpoint: /face/list_datasets
Response
{
"results": [
{
"dataset_id": "e1744eac-3f8a-447c-96cc-8aae63b3d6f9",
"dataset_name": "Hollywood Celebrities"
},
{
"dataset_id": "6d2ff8ea-ad4c-43c6-aabe-1da574d40cd6",
"dataset_name": "Football Players"
},
...
]
}
Delete Image
If you introduced a wrong image to a subject, or want to delete some of them, you can remove it with the following request by providing the image unique ID.
Request
curl -X POST \
-H "Api-Key: <token>" \
-F image_id=”3d64c2e5-42a9-497e-8185-b87ad62c0be8” \
http://api.visualintelligence.deepvisionai.com/face/delete_image
Endpoint: /face/delete_image
Request parameters
| image_id | string (required) Image unique id. |
Response
{
"image_id": "3d64c2e5-42a9-497e-8185-b87ad62c0be8"
}
Delete Subject
If you need to remove a subject in your Dataset, you can do it with the following request by providing the subject ID.
Request
curl -X POST \
-H "Api-Key: <token>" \
-F subject_id=”ec8c04a8-c4b0-481b-ab21-978845e730ed” \
http://api.visualintelligence.deepvisionai.com/face/delete_subject
Endpoint: /face/delete_subject
Request parameters
| subject_id | string (required) Image Subject id. |
Response
{
"subject_id": "ec8c04a8-c4b0-481b-ab21-978845e730ed"
}
Delete Dataset
If you need to remove your entire collection of images, use the request below.
Request
curl -X POST \
-H "Api-Key: <token>" \
-F dataset_id=”e1744eac-3f8a-447c-96cc-8aae63b3d6f9” \
http://api.visualintelligence.deepvisionai.com/face/delete_dataset
Endpoint: /face/delete_dataset
Request parameters
| dataset_id | string (required) ID of the Dataset you want to delete. |
Response
{
"dataset_id": "e1744eac-3f8a-447c-96cc-8aae63b3d6f9"
}
Edit Dataset
If you want to edit the name of your Dataset, you can proceed with the following request.
Request
curl -X POST \
-H "Api-Key: <token>" \
-F dataset_id=”e1744eac-3f8a-447c-96cc-8aae63b3d6f9” \
-F new_dataset_name=”Athletes” \
http://api.visualintelligence.deepvisionai.com/face/edit_dataset
Endpoint: /face/edit_dataset
Request parameters
| dataset_id | string (optional) Id of the Dataset that we want to edit. |
| new_dataset_name | string (required) New name to assign to the Dataset. |
Response
{
"dataset_id": "e1744eac-3f8a-447c-96cc-8aae63b3d6f9",
"dataset_name": "my_new_catalog"
}
Edit Subject
To change the name of one of your subjects, you can execute the request below.
Request
curl -X POST \
-H "Api-Key: <token>" \
-F subject_id=”ec8c04a8-c4b0-481b-ab21-978845e730ed” \
-F new_subject_name=”Brad Pitt” \
-F new_dataset_id=”6d2ff8ea-ad4c-43c6-aabe-1da574d40cd6” \
http://api.visualintelligence.deepvisionai.com/face/edit_subject
Endpoint: /face/edit_subject
Request parameters
| subject_id | string (required) Subject unique id.
|
| new_subject_name | string (optional) New name to assign to the Subject.
|
| new_dataset_id | string (optional) New dataset to assign to the Subject.
|
Response
{
"dataset_id": "e1744eac-3f8a-447c-96cc-8aae63b3d6f9",
"subject_id": "ec8c04a8-c4b0-481b-ab21-978845e730ed",
"subject_name": "Brad Pitt"
}
Edit Image
To change the alias name of your image, you can proceed with the following request.
Request
curl -X POST \
-H "Api-Key: <token>" \
-F image_id=”3d64c2e5-42a9-497e-8185-b87ad62c0be8” \
-F new_subject_id=”ec8c04a8-c4b0-481b-ab21-978845e730ed” \
-F new_image_alias=”Brad Photo 01” \
http://api.visualintelligence.deepvisionai.com/face/edit_image
Endpoint: /face/edit_image
Request parameters
| image_id | string (required) Image unique id.
|
| new_subject_id | string (optional) New Subject to assign to the Image.
|
| new_image_alias | string (optional) New alias to assign to the Image.
|
Response
{
"subject_id": "ec8c04a8-c4b0-481b-ab21-978845e730ed",
"image_id": "8a833b06-dbec-4732-a323-fec927ec0701",
"image_alias": "Brad Photo 01"
}
Visual Search
With Visual Search you can get the most visually similar items (meaning objects, products, etc) to the query image in your collection of images. This model allows you to add your own collection of images which define your Dataset (search space). The process requires three main steps:
-
Create an empty dataset (were your images will live)
-
Upload your own collection of images to the dataset
-
Perform Visual Search in your dataset, getting a ranked list of the most visually similar images as a response, with a similarity score associated with each result. You can perform a search in more than one dataset you've created at the same time.
Create a new Dataset
You can create a new and empty Dataset with the following request. You are allowed to create as many Datasets as you need. As a next step, you will need to add images to your Datasets and perform the search. Once a new Dataset is created, you will get the Dataset ID as response.
Request
curl -X POST \
-H "api-key: <token> \
-F dataset_name="my_catalogue1" \
http://api.visualintelligence.deepvisionai.com/search/add_dataset
Endpoint: /search/add_dataset
Request parameters
| dataset_name | string (optional) Dataset name given by user. |
Response
{
"dataset_id": "e1744eac-3f8a-447c-96cc-8aae63b3d6f9",
"dataset_name": "my_catalogue1"
}
Add Images to the Dataset
Once you've created your own Dataset, you can start uploading your collection of images which will define your search space. Each image can be supplied with a publicly accessible URL or by directly sending the image.
You must provide the Dataset ID (you got in the previous section) and the image URL or bytes.
Then, you have some optional parameters like "alias" which is an image name you can add for you to track your own names in your internal DB structure. The "hierarchy" parameter allows you to add the categories associated with the image (e.g if you upload an image of a table and it is associated with a structure in your categorization hierarchy, you can name it "home|interior|living room|tables"). With "subset_tag" you can tag images creating search subspaces so once you perform the search you will be able to narrow the search space down to the subset space you defined. Finally, with "left", "top", "right", "bottom" you can crop your image during the upload process.
Request
curl -X POST \
-H "api-key: <token>" \
-F dataset_id="e1744eac-3f8a-447c-96cc-8aae63b3d6f9" \
-F image="http://img.deepvisionai.com//visualintelligence/documentation/dining-room-example.jpg" \
-F alias="1256531" \
-F hierarchy="home|interior|living room|tables" \
-F subset_tag="my_tables" \
-F left=23 \
-F top=12 \
-F right=156 \
-F bottom=298 \
http://api.visualintelligence.deepvisionai.com/search/add_image
Endpoint: /search/add_image
Request parameters
| dataset_id | string (required) ID of the Dataset where the new image will be uploaded. |
| image | file (required) Image URL, bytes or base64 encoded image. |
| hierarchy | string (optional) Image hierarchy, each label must be separated by a pipe ("|"). |
| subset_tag | string (optional) Image subset name to create a search subspace. |
| alias | string (optional) Image alias name. |
| left | integer(optional) Image crop left coordinate. By default is set to 0. |
| top | integer (optional) Image crop top coordinate. By default is set to 0. |
| right | integer (optional) Image crop right coordinate. By default is set to image width. |
| bottom | integer (optional) Image crop bottom coordinate. By default is set to image height. |
Response
{
"image_id": "e1744eac-3f8a-447c-96cc-8aae63b3d6f9",
"image_alias": "1256531",
"image_hierarchy": "home|interior|living room|tables",
"image_subset_tag": "my_tables"
}
Search for similar images
Once you've created your Dataset and added your collection of images, you can start sending query images to the service and getting the most visually similar results ranked by similarity score.
You must provide the Dataset ID and the image URL or bytes. With "modes" = "default" you can start performing a search using the entire image.
Other 'modes' you can use are: (a) "default" which will perform the search using the entire image, (b) "selection" which combined with your image crop defined with "left", "top", "right", "bottom" will perform the search operation using a crop instead of the entire image; or (c) "auto_detect" which will detect objects automatically (This feature is only supported for Furniture and Home appliance objects at the moment). Then, "top_res" allow you to set how many results you need to get in your response. Finally, you can filter your Dataset (reduce your search space) either by subset tag with "by_subset_tag" = "my_tables" or by image category with "by_hierarchy" = "home|interior|living room|tables"
(Note: search filters are not supported yet).
Request
curl -X POST \
-F image=@/path/to/img/ \
-F dataset_id="8a833b06-dbec-4732-a323-fec927ec0701" \
-F modes="selection" \
-F by_subset_tag="my_tables" \
-F left=23 \
-F top=12 \
-F right=156 \
-F bottom=298 \
-F by_hierarchy="home|interior|living room|tables" \
-F top_res=10 \
http://visualintelligence.deepvisionai.com/search
Endpoint: /search
Request parameters
| image | file (required) Image URL, bytes or base64 encoded image. |
| dataset_id | string (optional) Dataset ID where we want to perform the search. If it's no specified the search is performed in all your datasets. |
| modes | string (required) One of "default", "selection" or "auto_detect". |
| left | number (optional) Image crop left coordinate. By default is set to 0. |
| top | number (optional) Image crop top coordinate. By default is set to 0. |
| right | number (optional) Image crop right coordinate. By default is set to image width. |
| bottom | number (optional) Image crop bottom coordinate. By default is set to image height. |
| top_res | number (optional) Amount of results to return. By default is set to 30, the maximum is 100. |
| by_subset_tag | string (optional) Name of the subset in which the search will be performed. If no subset is specified, the
search is performed in the whole dataset. |
| by_hierarchy | string (optional) Not supported yet. |
Response
[
{
"bbox": {
"left": 23,
"top": 12,
"right": 156,
"bottom": 298
},
"similar_images": [
{
"dataset_id": "8a833b06-dbec-4732-a323-fec927ec0701",
"image_id": "7bc1684a-7b4e-479b-8dd6-8dffef3b2a4e",
"image_alias": "1256531",
"image_hierarchy": "home|interior|living room|tables",
"image_subset_tag": "my_tables",
"similarity_score": 0.453432
},
...
]
}
]
Get Image URL
Sometimes you may want to download the image file associated with your “image_id”. To do this, we provide the following method which retrieves an URL for you to access to the image. For privacy purposes, the provided image URL will expire within one hour.
Request
curl -X POST \
-F image_id="7bc1684a-7b4e-479b-8dd6-8dffef3b2a4e" \
http://visualintelligence.deepvisionai.com/search
Endpoint: /search/image_url
Request parameters
| image_id | string (required) Id of the image. |
Response
{
"image_id": "7bc1684a-7b4e-479b-8dd6-8dffef3b2a4e",
"image_url": "api.visualintelligence.deepvisionai.com/e6a3f8da-9d0ed3687771.jpeg"
}
List Datasets
You can list your Datasets with the following request and you'll get a list of all Datasets IDs plus their corresponding names.
Request
curl -X POST \
-H "api-key: <token>" \
http://api.visualintelligence.deepvisionai.com/search/list_datasets
Endpoint: /search/list_datasets
Response
{
"results": [
{
"dataset_id": "8a833b06-dbec-4732-a323-fec927ec0701",
"dataset_name": "my_catalogue"
},
...
]
}
List images
With the following request, you can get the list of images contained in your Datasets. You can get a filtered list of images by setting "hierarchy" or "subset_tag" parameters (Note: this method is not supported yet).
Request
curl -X POST \
-H "api-key: <token>" \
-F dataset_id="e6a3f8da-7b77-4c12-8499-9d0ed3687771" \
-F hierarchy="home|interior|living room|tables" \
-F subset_tag="my_tables" \
http://api.visualintelligence.deepvisionai.com/search/list_images
Endpoint: /search/list_images
Request parameters
| dataset_id | string (optional) ID of the Dataset. If it's no provided all the images (from all your Datasets) are listed. |
| hierarchy | string (optional) Not supported yet. |
| subset_tag | string (optional) Not supported yet. |
Response
{
"results": [
{
"dataset_id": "e6a3f8da-7b77-4c12-8499-9d0ed3687771",
"image_id": "e1744eac-3f8a-447c-96cc-8aae63b3d6f9",
"image_alias": "1256531",
"image_hierarchy": "home|interior|living room|tables",
"image_subset_tag": "tables group"
},
...
]
}
Edit Dataset
With this request, you can edit your Dataset attributes like name.
Request
curl -X POST \
-H "api-key: <token>" \
-F dataset_id="e6a3f8da-7b77-4c12-8499-9d0ed3687771" \
-F new_dataset_name="my_new_catalog" \
http://api.visualintelligence.deepvisionai.com/search/edit_dataset
Endpoint: /search/edit_dataset
Request parameters
| dataset_id | string (optional) Id of the Dataset that we want to edit. |
| new_dataset_name | string (required) New name to assign to the Dataset. |
Response
{
"dataset_id": "e6a3f8da-7b77-4c12-8499-9d0ed3687771",
"dataset_name": "my_new_catalog"
}
Edit Image
With the following request, you can move an Image from one Dataset to another, or change image hierarchy, subset_tag, and alias.
Request
curl -X POST \
-H "api-key: <token>" \
-F image_id="7bc1684a-7b4e-479b-8dd6-8dffef3b2a4e" \
-F new_dataset_id="8a833b06-dbec-4732-a323-fec927ec0701" \
-F new_hierarchy="home|interior|living room|tables" \
-F new_subset_tag="tables_group" \
-F new_alias="1256531" \
http://api.visualintelligence.deepvisionai.com/search/edit_image
Endpoint: /search/edit_image
Request parameters
| image_id | string (required) Id of the image that we want to edit. |
| new_dataset_id | string (optional) Id of the Dataset that we want to assign to the image. |
| new_hierarchy | string (optional) New hierarchy for the image. |
| new_subset_tag | string (optional) New subset for the image. |
| new_alias | string (optional) New alias for the image. |
Response
{
"image_id": "7bc1684a-7b4e-479b-8dd6-8dffef3b2a4e",
"dataset_id": "8a833b06-dbec-4732-a323-fec927ec0701",
"image_alias": "1256531",
"image_hierarchy": "home|interior|living room|tables",
"subset_tag": "tables group",
}
Delete Dataset
Delete a Dataset and all the images associated with it.
Request
curl -X POST \
-H "api-key: <token>" \
-F dataset_id="e6a3f8da-7b77-4c12-8499-9d0ed3687771" \
http://api.visualintelligence.deepvisionai.com/search/delete_dataset
Endpoint: /search/delete_dataset
Request parameters
| dataset_id | string (required) ID of the Dataset you want to delete. |
Response
{
"dataset_id": "e6a3f8da-7b77-4c12-8499-9d0ed3687771"
}
Delete Image
Delete an Image from a Dataset.
Request
curl -X POST \
-H "api-key: <token>" \
-F image_id="7bc1684a-7b4e-479b-8dd6-8dffef3b2a4e
http://api.visualintelligence.deepvisionai.com/search/delete_image
Endpoint: /search/delete_image
Request parameters
| image_id | string (required) ID of the Image you want to delete. |
Response
{
"image_id": "7bc1684a-7b4e-479b-8dd6-8dffef3b2a4e",
"image_alias": "1256531",
"image_hierarchy": "home|interior|living room|tables",
"image_subset_tag": "tables group"
}
Delete all
Delete all your Datasets at once including all their Images. You will get as response a list containing the ID of each Dataset you removed with the number of images that were removed.
Request
curl -X POST \
-H "api-key: <token>" \
http://api.visualintelligence.deepvisionai.com/search/delete_all
Endpoint: /search/delete_all
Response
{
"results": [
{
"dataset_id": "e6a3f8da-7b77-4c12-8499-9d0ed3687771",
"image_images": 42
},
...
]
}