New to Peltarion? Discover our deep learning Platform

A single deep learning platform to build and deploy your projects, even if you’re not an AI superstar.

Deployment API

Prerequisites

You need to create a deployment from the deployment view. The deployment view will show you the information you need to use the Deployment API:

All the input and output names (and shapes) of your model
The URL and deployment token to use for your requests
The status of the deployment. Make sure it is enabled, or requests will be denied

Structure of a prediction request

To submit examples, you use a HTTP client to send a POST request to the URL indicated on the deployment page that you want to use.

You can send such requests by using cURL, Python (e.g., with the requests package), or our sidekick tool for Python. Other packages, languages, or tools may also be used if they follow the API specifications.

Header

Your request must always have a header, which is a JSON formatted string. The header must contain the deployment token, which is used to authenticate the request.

It must also contain the format of the request’s payload. The Deployment API only accepts JSON formatted payload, so the header looks like this:

{
    'Authorization': 'Bearer <token>'
    'Content-Type': 'application/json',
}

Payload

To submit examples, you attach them in the payload of the request. The payload is also a JSON formatted string, which contains the features of one or more examples to be evaluated.

The structure of the JSON payload has a single key called rows, associated with a comma-separated array of examples.
Each example is a collection of key-value pairs, where the keys are the names of the input features of the model.

For instance, if your deployment parameters look like this in the deployment view:

Then the JSON payload to submit 4 examples will look like this:

{
    "rows": [
        {"Type": "animal", "Sound": "miaow", "Size": 0.4},
        {"Type": "animal", "Sound": "woof", "Size": 1.2},
        {"Type": "vehicle", "Sound": "tchoo", "Size": 80},
        {"Type": "vehicle", "Sound": "vroom", "Size": 3.2}
    ]
}

Note that you don’t need to have line breaks inside your payload, and it could look like this:

{"rows": [{"Type": "animal", "Sound": "miaow", "Size": 0.3},{"Type": "animal", "Sound": "woof", "Size": 1.2},{"Type": "vehicle", "Sound": "tchoo", "Size": 80},{"Type": "vehicle", "Sound": "vroom", "Size": 3.2}]}

Response

Once you send the request with a valid header and payload, your model will run the examples submitted and return predictions for each of them.

The predictions are given as a JSON formatted text string. The structure is identical to that of the payload, except that each example contains a single key-value pair, where the key is the name of the output feature.
The response to the example request above would look like this:

{
    "rows": [
        {"Weight": 1.2},
        {"Weight": 4.7},
        {"Weight": 900000},
        {"Weight": 3000}
    ]
}

Examples

Submitting tabular data

Tabular data is data whose features could be submitted inside a CSV file (i.e., single numeric value, categorical, or text).

Here are examples for submitting one example.

Sidekick

import sidekick

query = [{"Type": "animal", "Sound": "Miaow", "Size": 0.26}]

client = sidekick.Deployment(url=<URL>, token=<token>)
response = client.predict_many(query)

Python

Submit a JSON formatted string as payload:

import requests

url = <URL>
token = <token>
header = {'Authorization': 'Bearer {}'.format(token), 'Content-Type': 'application/json'}

payload = '{"rows": [{"Type": "animal", "Sound": "Miaow", "Size": 0.43}]}'
response = requests.request("POST", url, headers=header, data=payload)

Note that payload is a text string, but header can be passed directly as a Python dictionary object. You can also pass the payload as a Python dictionary object by using the json argument instead of data:

Submit a Python dictionary object as payload:

payload = {"rows": [{"Type": "animal", "Sound": "Miaow", "Size": 0.43}]}
response = requests.request("POST", url, headers=header, json=payload)

cURL

Submit a JSON formatted payload string:

curl -X POST \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json"  \
-d '{"rows": [{"Type": "animal", "Sound": "Miaow", "Size": 0.43}]}' \
<URL>

Submit an example with cURL options:

As with Python, you can use cURL to send data using native options, rather than sending a JSON formatted string. With cURL, however, you can only submit one example at a time this way.

curl -X POST \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-F "Type=animal" \
-F "Sound=woof" \
-F "Size=1.3" \
<URL>

Submitting images

You can also submit examples that have images as some of their features. The submission is always done via a JSON formatted text string, so you need to transform the images into text. The following examples show how to create a payload that you can use as above when some features are examples.

Sidekick

import sidekick
from PIL import Image

query = [{'Feature Name': Image.open('images/Number_6.png')},
         {'Feature Name': Image.open('images/Number_7.png')}]

client = sidekick.Deployment(url='<URL>', token='<token>')
response = client.predict_many(query)

Python

import base64
import os

def encode_image(image_file, img_type):
    encoded_image = 'data:image/{};base64,'.format(img_type) + base64.b64encode(image_file.read()).decode('ascii')
    return encoded_image

# The path to the image file
img_path = "images/Number_6.png"
# The image extension, 'jpg' and 'png' are supported
img_type = os.path.splitext(img_path)[-1][1:]

with open(img_path, "rb") as image_file:      # read file as binary
    image_as_text = encode_image(image_file, img_type)

payload = {"rows": [{"Feature Name": image_as_text, "Sound": "Miaow", "Size": 0.43}]}

url = <URL>
token = <token>
header = {'Authorization': 'Bearer {}'.format(token), 'Content-Type': 'application/json'}

response = requests.request("POST", url, headers=header, json=payload)

curl

curl -X POST \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json"  \
-F "Feature Name=@Number_6.png" \
<URL>

Submitting numpy arrays

Python

As for images, you need to convert the .npy numpy files into text to submit them as a feature inside a request’s payload.

import base64

def encode_npy(npy_file):
    encoded_npy = 'data:application/x.peltarion.npy;base64,' + base64.b64encode(npy_file).decode('ascii')
    return encoded_npy

# The path to the npy file
npy_path= "files/array.pny"

with open(npy_path, "rb") as npy_file:      # read file as binary
    npy_as_text = encode_npy(npy_file)

payload = {"rows": [{"Numpy Feature": npy_as_text, "Sound": "Miaow", "Size": 0.43}]}

Sometimes, you may want to submit a numpy array without saving it as a .npy file on your disk first. To do this, you can use a buffer, together with the same encode_npy function as when reading .npy files from disk.

import numpy
import base64
import io

data = numpy.zeros((32,32))         # The numpy array used as feature

buffer = io.BytesIO()
numpy.save(buffer, data)
npy_value = encode_npy(buffer.getvalue())

payload = {"rows": [{"Numpy Feature": npy_as_text, "Sound": "Miaow", "Size": 0.43}]}

curl

curl -X POST \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json"  \
-F "Numpy Feature=@array.pny" \
<URL>

Working with responses

When you submit a request, you will get a standard HTTP code telling you if the operation was successful or not. A value in the two hundreds usually indicate success, and four to five hundred indicates an error.

When successful, you will also receive a JSON formatted string as the payload of the response. This string contains the predictions for the list of submitted examples, or an error message if there was a problem (e.g., one of the examples submitted contained invalid data).

Python

After sending a prediction request, e.g.,

import requests

url = <URL>
token = <token>
header = {'Authorization': 'Bearer {}'.format(token), 'Content-Type': 'application/json'}

payload = '{"rows": [{"Type": "animal", "Sound": "Miaow", "Size": 0.43}]}'
response = requests.request("POST", url, headers=header, data=payload)

you can get the status code with status_code:

print(response.status_code)

and the JSON message with json():

print(response.json())

cURL

In cURL, the status code should be displayed when you submit a command. You may need to use the verbose -v option to get more feedback from cURL.

Understanding prediction results

The predictions for 2 submitted examples look like this:

{'rows': ['output name': value1, 'output name': value2]}

Depending on the type of the output, the JSON object value1 can have different forms.

Numeric predictions

For numeric predictions (single number), the value is returned directly. The message looks like this:

{'rows': ['output name': 0.3740423, 'output name': 6.784281]}

Categorical predictions

For categorical predictions, every possible category is returned as a key, and the associated value gives the probability of the example belonging to that class. For example:

{'rows': ['output name': {'cat': 0.98, 'dog': 0.005, 'train': 0.005, 'car':0.01 }, 'output name': {'cat': 0.001, 'dog': 0.001, 'train': 0.899, 'car':0.1 }]}

Image predictions

If the output of the model is an image, it is returned encoded as a text string.

Python

In python, you can convert it back like this:

import base64

def decode(image_text):
    return base64.b64decode(res['path_clean'].split(',')[-1])

image_encoded = response['rows'][0]['Image Output Name']
image = decode(image_encoded)

# save it to disk
with open('/output/path/image.jpg', 'bw') as outf:
        outf.write(image)

#display it
plt.imshow(image)

NPY predictions

As for images, if the output is a numpy array, it is returned encoded as text.

Python

In Python, you can convert it back like this:

import base64

def decode_npy(encoded_numpy):
    data_base64 = encoded_numpy.split(',')[1]
    data_numpy = decode_base64(data_base64)
    return np.array(data_numpy)

TRY FOR FREE