Back to top

Visual Intelligence API



DeepVision’s Visual Intelligence 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 allowing face counting. 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.




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://deepvisionai.com/img/visualintelligence/documentation/example.jpg",
        "context":{
            "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)",
        "context":{
            "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": []
        },
        ...
    ]
}

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. Note: Other modes will be supported for face recognition and demographics.

Request

curl -X POST \
    -H "Api-Key: <token>" \
    -H "Content-Type: application/json" \
    -d '
    {
        "image":"http://deepvisionai.com/img/visualintelligence/documentation/example.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
            }
        }
    ]
}

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 services calls.

Request

curl -X POST \
    -H "Api-Key: <token>" \
    -H "Content-Type: application/json" \
    -d '
    {
        "image":"http://deepvisionai.com/img/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 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://deepvisionai.com/img/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_hierarchy string (optional) Not supported yet.
by_subset_tag 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
        },
        ...
    ]
}