NAV Navbar
python json

Introduction

Welcome to the Overture documentation. You can use our REST API or SDK to access our platform, which gives you access to your custom-built computer vision neural networks.

We currently have a REST API and a supported Python SDK.

Register an account and start training, deploying and using your own custom-trained neural networks.

Getting started

If you are registered on the platform you can start using the Overture platform. First things first, before you can start using our powerful computer vision models, you will need to train and deploy your custom-built neural networks.

Once you have a trained model in your models portal, you can start using them through our REST API or official Python SDK.

Installing the Python SDK

pip install --upgrade overture-sdk

Installing the official Python SDK is easily done through PyPi. After intalling the package through pip, you can start developing computer vision enabled applications using the SDK.

The SDK is still in beta, we highly encourage to submit any bugs or feature requests to [email protected]

Currently Python 2.7, 3.4, 3.5, 3.6, 3.7 is supported.

Training

Before you can start to use computer vision neural networks, you will need to create and train them for your specific use case. Go to the model hub and start training your specific computer vision model.

Deployment

Is your custom neural network finished training? Awesome! You can start deploying it in the deployment portal. Once successfully deployed you can start using it for inference through the official Overture REST API or Python SDK.

Authentication

Overture uses API keys to authorize prediction API calls to your custom built neural network. Every neural network is associated with a unique API key and model identifier which can be found in your integrations portal.

Overture expects for the API key to be included in all API requests to the server in a header that looks like the following:

x-api-key: dummyapikey

Inference

Object Detection

from overture.predictions import ObjectDetection

objectDetect = ObjectDetection(apikey="dummykey", model_id="123")

# perform a prediction
result = objectDetect.predict("example.png")

# perform a batch prediction
result = objectDetect.predict_batch(["example1.png", "example2.png"])

Object detection can be used to analyze images and detect whether and where objects are located on images. Overture is capable of training neural networks to recognize the specific objects that you like, start in the model hub.

Once you have successfully trained and deployed an object detection you can use the HTTP request below to analyze images using your custom built object detection neural network.

HTTP Request

POST https://models.overture.ai/predict/image/objectdetection

Request Body

{
  "model_id": "string",
  "images": [
    {
      "filename": "string",
      "image": "urlsafe base64 representation of the image"
    }
  ]
}

Up to 5 images in one JSON request body are supported, this number might increase in future releases.

Body Parameters

Parameter Required Description
model_id true An integer that identifies the model you want to use.
images true An array containing JSON objects of the images that need to be analyzed with a maximum of 5 images per request.

Response Body

[
  {
    "input": "the filename of the processed image",
    "info": {
      "width": "integer that describes the width of the image",
      "height": "integer that describes the height of the image"
    },
    "output": [
      {
        "label": "the label of the object that got detected",
        "bounding_coordinates": [
          "integer"
        ]
      }
    ]
  }
]

The JSON response object contains an entry for every submitted image. The bounding_coordinates property contains an array of integers that describe a bounding box, where:

Error Codes

Code String Description
400 INVALID_LIST_IMAGES_UPLOADED You did not upload a base-64 urlsafe encoded image string or too much images.
400 INVALID_MODEL_ID You defined an invalid model identifier or one which you don't have access to, check your API key.

Image Classification

from overture.predictions import ImageClassification

classification = ImageClassification(apikey="dummykey", model_id="123")

# perform a prediction
result = classification.predict("example.png")

# perform a batch prediction
result = classification.predict_batch(["example1.png", "example2.png"])

Image classification can be used to classify images into specific categories. Overture is capable of training neural networks to recognize the specific categories of images that you like, start in the model hub.

Once you have successfully trained and deployed an image classifier, you can use the HTTP request below to analyze images using your custom built image classification neural network.

HTTP Request

POST https://models.overture.ai/predict/image/classification

Request Body

{
  "model_id": "string",
  "images": [
    {
      "filename": "string",
      "image": "urlsafe base64 representation of the image"
    }
  ]
}

Up to 10 images in one JSON request body are supported, this number might increase in future releases.

Body Parameters

Parameter Required Description
model_id true An integer that identifies the model you want to use.
images true An array containing JSON objects of the images that need to be analyzed with a maximum of 10 images per request.

Response Body

[
  {
    "filename": "string",
    "confidence": {
      "label_1": "float",
      "label_2": "float",
      "label_n": "float"
    }
  }
]

The JSON response object contains an array with an entry for every submitted image. For every image a confidence array is included with an entry for every label on which the classifier is trained with the respective confidence score. The confidence score is a float value between 0 and 1.0. The higher the confidence score the more certain the network is.

Error Codes

Code String Description
400 INVALID_LIST_IMAGES_UPLOADED You did not upload a base-64 urlsafe encoded image string or too much images.
400 INVALID_MODEL_ID You defined an invalid model identifier or one which you don't have access to, check your API key.

Face Recognition

from overture.predictions import FaceRecognition

recognition = FaceRecognition(apikey="dummykey", model_id="123")

# perform a prediction
result = recognition.predict("example.png")

# perform a batch prediction
result = recognition.predict_batch(["example1.png", "example2.png"])

Face recognition can be used to recognize people on images. Overture is capable of training neural networks to recognize faces of specific persons on images, start in the model hub.

Once you have successfully trained and deployed a face recognizer, you can use the HTTP request below to analyze images using your custom built face recognition neural network.

HTTP Request

POST https://models.overture.ai/predict/image/facerecognition

Request Body

{
  "model_id": "string",
  "images": [
    {
      "filename": "string",
      "image": "urlsafe base64 representation of the image"
    }
  ]
}

Up to 5 images in one JSON request body are supported, this number might increase in future releases.

Body Parameters

Parameter Required Description
model_id true An integer that identifies the model you want to use.
images true An array containing JSON objects of the images that need to be analyzed with a maximum of 5 images per request.

Response Body

[
  {
    "input": "string",
    "info": {
      "width": "integer",
      "height": "integer"
    },
    "output": [
      {
        "person": "string",
        "bounding_coordinates": [
          "integer"
        ]
      }
    ]
  }
]

The JSON response object contains an entry for every submitted image. The bounding_coordinates property contains an array of integers that describe a bounding box, where:

Error Codes

Code String Description
400 INVALID_LIST_IMAGES_UPLOADED You did not upload a base-64 urlsafe encoded image string or too much images.
400 INVALID_MODEL_ID You defined an invalid model identifier or one which you don't have access to, check your API key.

Health

from overture.predictions import ImageClassification

classification = ImageClassification(apikey="dummykey", model_id="123")

# check if the model is online
isOnline = classification.is_healthy()
print("Model online: {}".format(isOnline))

Check if a trained model is deployed online.

HTTP Request

GET https://models.overture.ai/health/<model_id>

URL Parameters

Parameter Required Description
model_id true An integer that identifies the model you want to check the health of.

Response Body

A status code 200 is returned if the model is up and running, 400 in any other case.