Back to top

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.

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 1,000+ YMM (all vehicles of the past 10 years in the US) 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": "Front Left View",
            "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 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:

  1. Create an empty dataset
  2. Add a new subject to the dataset
  3. Add images to the given subject
  4. 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:

  1. Create an empty dataset (were your images will live)

  2. Upload your own collection of images to the dataset

  3. 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"
}

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
        },
        ...
    ]
}