Back to top

Visual Intelligence API



DeepVision’s Visual Intelligence API is composed by the following main modules described below:

Visual Face

This module allows you to get the coordinate locations of the detected faces plus who is in the photo. The model is able to recognize 5.000(s) celebrities so far, although custom names can be added to the model upon request. It also gives you demographic information about people like age and gender, based on face appearances.

Visual Brand

With Visual Brands you can detect and recognize the brands appearing in your images. You can try logos like Coca cola, Starbucks, Oreo, Adidas, Budweiser, Nike, Pepsi, Heineken, Dell, Apple, Reebok, etc, although new custom logos are added to our models upon request.

Visual Context

With Visual Context you can predict tags and concepts over a wide range of general topics. By combining it with Visual Face and Visual Brand you can discover under which context this people and brands are appearing in your images.




Authentication


How to get access?

To get access to our Visual Intelligence API please contact us, you just need to request your token. Then, with your token, you can start sending requests to Visual Intelligence API.




Predict


With Predict, you can understand your images and get the most value out of them. Using our Visual Intelligence API is very easy and straightforward:

Predict with an URL

With the following request you can send your image URL to the API and you’ll get a full list of concepts and it’s corresponding probabilities telling you how likely we are about those concepts are in your image. You can choose whether you want all the models (Visual Face, Visual Brand and Visual Context) running at the same time, or just a combination of them.

Request

curl -X POST visualintelligence.deepvisionai.com/image_url?url_auth_token=<token> -F url=http://deepvisionai.com/img/us/team.png

Endpoint: /image_url

Query parameters

url_auth_token string Your access token to the API.

Post parameters

computeFace string Must be either “true” or “false”. Defaults to “true”.
computeBrand string Must be either “true” or “false”. Defaults to “true”.
computeContext string Must be either “true” or “false”. Defaults to “true”.
faceAge string Must be either “true” or “false”. Defaults to “true”.
faceGender string Must be either “true” or “false”. Defaults to “true”.
faceRecognize string Must be either “true” or “false”. Defaults to “true”.
url string (required) URL of image to be downloaded.

Response

{
  "boxes": [
    {
      "left": 294, 
      "top": 317, 
      "right": 508,
      "bottom": 400, 
      "brand": {
        "score": 0.86217,
        "value": "nike"
      }
    },
    {
      "left": 294, 
      "top": 317, 
      "right": 508,
      "bottom": 400, 
      "face__age": {
        "score": 0.86217,
        "value": 42
      }, 
      "face__gender": {
        "score": 0.86217,
        "value": "male"
      }, 
      "face__recognize": {
        "score": 0.86217,
        "value": "Di Caprio"
      }
    }
  ], 
  "tags": [
    {
      "tag": ["footwear", "shoes"], 
      "score": 0.11, 
      "related_tags": [
        "flexible upper", 
        "heavier material", 
        "sole"
      ]
    }
  ]
  "image": "data:image/jpeg;base64,ab238978c6de9872...",
  "width": 800,
  "height": 600
}

Predict by uploading an image

In this case, instead of sending an image URL, we are providing the image file to the API. You’ll get exactly the same response as before but now passing your image in a different way.

Request

curl -X POST visualintelligence.deepvisionai.com/upload_image?url_auth_token=<token> -F file=@/path/to/img/

Endpoint: /upload_image

Query parameters

url_auth_token string Your access token to the API.

Post parameters

computeFace string Must be either “true” or “false”. Defaults to “true”.
computeBrand string Must be either “true” or “false”. Defaults to “true”.
computeContext string Must be either “true” or “false”. Defaults to “true”.
faceAge string Must be either “true” or “false”. Defaults to “true”.
faceGender string Must be either “true” or “false”. Defaults to “true”.
faceRecognize string Must be either “true” or “false”. Defaults to “true”.
image file (required) Attach a single image to your request.

Response

{
  "boxes": [
    {
      "left": 294, 
      "top": 317, 
      "right": 508,
      "bottom": 400, 
      "brand": {
        "score": 0.86217, 
        "value": "nike"
      }
    },
    {
      "left": 294, 
      "top": 317, 
      "right": 508,
      "bottom": 400, 
      "face__age": {
        "score": 0.86217,
        "value": 42
      }, 
      "face__gender": {
        "score": 0.86217,
        "value": "male"
      }, 
      "face__recognize": {
        "score": 0.86217,
        "value": "Di Caprio"
      }
    }
  ], 
  "tags": [
    {
      "tag": ["footwear"], 
      "score": 0.11, 
      "related_tags": [
        "flexible upper", 
        "heavier material", 
        "sole"
      ]
    }
  ]
}



Visual Search


With this module you can get the most visually similar products to the query image in your collection of images. This process requires two steps:

  1. You need to upload your collection of images,

  2. Then, you can query with new images and you’ll be able to find the most similar products in your collection.

The model will return a ranked list of images and similarity scores based on how similar the results are when compared to the query image.

Add images to the database

With the following request, you’ll be able to upload your collection of images. You can add an alias “name” to your images so that you can find them in your system later on. In addition, you can add an ID or name to your subset of images, so you can then search only in that subset space.

Request

curl -X POST visualintelligence.deepvisionai.com/add_product?url_auth_token=<token> -F image=@/path/to/img/ -F imageId=ab21bc123 -F subset=phones

Endpoint: /add_product

Query parameters

url_auth_token string Your access token to the API.

Post parameters

image file (required*) Attach a single image to your request.
imageUrl string (required*) URL of image that will be downloaded.
imageId string (required) Identifier of the product.
subset string optional Name of the subset of images.
  • You must send either image or imageUrl, but you can’t send both at the same time.

Response

If successful, this endpoint returns the HTTP code 204 (No Content). There’s no output to parse.

Delete images from the database

With this request, you can also delete the images you don't need anymore in your collection of images.

Request

curl -X DELETE visualintelligence.deepvisionai.com/delete_product?url_auth_token=<token>&imageId=ab21bc123

Endpoint: /delete_product

Query parameters

url_auth_token string Your access token to the API.
imageId string The id of the image to be deleted.

Response

This endpoint returns the HTTP code 200. The response content confirms the deletion of the image.

Deleted ab21bc123

Query for similar images

With the following request, you can query the model with your image and you’ll get the top 5 most visually similar results from your collection of images.

Request

curl -X POST visualintelligence.deepvisionai.com/find_product?url_auth_token=<token> -F image=@/path/to/img/

Endpoint: /find_product

Query parameters

url_auth_token string Your access token to the API.

Post parameters

subset string optional Name of the subset in which close images will be searched. If not set, all images are evaluated.
results number optional Amount of results that will be returned. Defaults to 5.
image file (required*) Attach a single image to your request.
imageUrl string (required*) URL of image that will be downloaded.
  • You must send either image or imageUrl, but you can’t send both at the same time.

Response

[
  {
    "score": 0.972312,
    "image": "visualintelligence.deepvisionai.com/image1.jpg",
    "imageId": "123ab21cd78e4623"
  },
  {
    "score": 0.95421,
    "image": "visualintelligence.deepvisionai.com/image2.jpg",
    "imageId": "21cd78e4623123ab"
  },
  {
    "score": 0.913434,
    "image": "visualintelligence.deepvisionai.com/image3.jpg",
    "imageId": "4623123ab21cd78e"
  },
  {
    "score": 0.872312,
    "image": "visualintelligence.deepvisionai.com/image4.jpg",
    "imageId": "b21cd7123a8e4623"
  },
  {
    "score": 0.823223,
    "image": "visualintelligence.deepvisionai.com/image5.jpg",
    "imageId": "1cd78e4623123ab2"
  }
]