UnityPredict API

Introduction

This guide provides all the necessary details for utilizing the UnityPredict prediction APIs. These APIs empower developers to make predictions against models hosted on UnityPredict using simple API calls.

The base endpoint for accessing UnityPredict APIs is:

shell

https://api.prod.unitypredict.com/api

API Invocation for Models without Input Files

Invoking a model that doesn't have any file inputs (i.e. doesn't require a file upload) is very simple and can be done by simply making a POST to the predict endpoint.

Sample Predict Endpoint API Call

shell

curl --request POST --url https://api.prod.unitypredict.com/api/predict/{model-id} \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer APIKEY@{yourApiKey}' \
--data '{
    "InputValues": {
        "Age": 61,
        "Chol": 120
    },
    "DesiredOutcomes": [
        "Label"
    ]
}'

Request Parameters

model-id: The unique model Id of the model that is to be called. This appears in the url/address bar and can also be copied using the copy icon next to the predict button on the inference page (see screenshot below).
yourApiKey: The API key value that you have created on the Profile page of your UnityPredict account.
The json body needs to contain the following fields:
- InputValues: a key-value map of the input variables
- DesiredOutcomes: list of output variable names that you want to get back from the model

Sample Response JSON

json

{
    "contextId": "unitypredict-context-uuid",
    "requestId": "unitypredict-request-uuid",
    "errorMessages": "",
    "computeTime": "00:00:02.4778178",
    "computeTimeCharged": "00:00:02.4778190",
    "computeCost": 0.0002477819,
    "outcomes": {
        "Label": [
            {
                "dataType": "Boolean",
                "probability": 0.015924746,
                "value": false
            }
        ]
    },
    "status": "Completed"
}

Response Parameters

contextId: A unique Id that is linked to the user session. If the model support 'Context' (ex. ChatBots), sending the same contextId on the next predict call will make sure that the model has access to the previous history of inferences from the same context.
requestId: A unique identifier of this particular call. This can be used to check the status of inference in long-running jobs.
status: Returns the inference status (see below). If this value is returned as Processing, it means the model needs more time to complete inference (see status API section).
errorMessages: Any error messages that happened during inference.
computeTime: Total run time for inference.
computeTimeCharged: Amount of compute time actually charged. For some more optimized models, this value can be shorter than computeTime
computeCost: Total cost of inference. This is charged to the account linked to the API key used for making the call.
outcomes: Contains the output values and probabilities (if provided by the model). Note: some models return multiple values for a single variable.

Response Codes

Response Code	Short Description	Long Description
200	Success	The request was successful.
400	Bad Request	The request was invalid.
401	Unauthorized	Authentication of the API key failed.
403	Forbidden	Access denied.
404	Not Found	The resource was not found.
500	Internal Server Error	An unexpected error occurred on the server.

Status Codes

Status	Status Description
"Completed"	Engine has successfully completed its execution
"Error"	Engine has faced errors during execution. Check `errorMessages` for error details
"Processing"	Engine is still processing the prediction
None	No status from Engine detected. Possibly due to server errors

Checking Status of Long-Running Inferences

To avoid timeouts in consumers of the API, UnityPredict restricts the runtime of predict endpoint REST calls to 30 seconds. Since some AI models/solutions require more time to run, the API will return Processing status in the response if the model does not finish in time. In this case, you can use check the status of a particular request using the RequestId returned from the predict API call. The response model for this endpoint will be exactly the same as the original predict endpoint. Once the inference is complete, the status will return as Completed.

shell

curl --request GET --url https://api.prod.unitypredict.com/api/predict/status/{request-id} \
--header 'Authorization: Bearer APIKEY@{yourApiKey}'

Request Parameters

request-id: The unique request identifier returned by the original call to the predict endpoint

Response Parameters

contextId: A unique Id that is linked to the user session. If the model support 'Context' (ex. ChatBots), sending the same contextId on the next predict call will make sure that the model has access to the previous history of inferences from the same context.
requestId: A unique identifier of this particular call. This can be used to check the status of inference in long-running jobs.
status: Returns the inference status (see below). If this value is returned as Processing, it means the model needs more time to complete inference (see status API section).
errorMessages: Any error messages that happened during inference.
computeTime: Total run time for inference.
computeTimeCharged: Amount of compute time actually charged. For some more optimized models, this value can be shorter than computeTime
computeCost: Total cost of inference. This is charged to the account linked to the API key used for making the call.
outcomes: Contains the output values and probabilities (if provided by the model). Note: some models return multiple values for a single variable.

Response Codes

Response Code	Short Description	Long Description
200	Success	The request was successful.
400	Bad Request	The request was invalid.
401	Unauthorized	Authentication of the API key failed.
403	Forbidden	Access denied.
404	Not Found	The resource was not found.
500	Internal Server Error	An unexpected error occurred on the server.

Downloading Generated Output File(s)

Some models may produce output files (i.e. variables with data type of File). When the response is received from the predict endpoint, only the output file name is shown in the outcomes. Below is an example of such a response.

json

{
    "contextId": "unitypredict-context-uuid",
    "requestId": "unitypredict-request-uuid",
    "errorMessages": "",
    "computeTime": "00:00:02.4778178",
    "computeTimeCharged": "00:00:02.4778190",
    "computeCost": 0.0002477819,
    "outcomes": {
        "TranscriptFile": [
            {
                "dataType": "File",
                "probability": 0.0,
                "value": "generated_transcript.txt"
            }
        ]
    },
    "status": "Completed"
}

In order to retrieve/download the generated output, you will need to use the download endpoint as shown below. Notice that the file name will be whatever value is returned for the output variable's value.

shell

curl --request GET --url https://api.prod.unitypredict.com/api/predict/download/{request-id}/{file_name} \
--header 'Authorization: Bearer APIKEY@{yourApiKey}'

Request Parameters

request-id: The unique request identifier returned by the original call to the predict endpoint
yourApiKey: The API key value that you have created on the Profile page of your UnityPredict account.

Response Codes

Response Code	Short Description	Long Description
200	Success	The request was successful.
400	Bad Request	The request was invalid.
401	Unauthorized	Authentication of the API key failed.
403	Forbidden	Access denied.
404	Not Found	The resource was not found.
500	Internal Server Error	An unexpected error occurred on the server.

API Invocation for Models with Input Files

When using the API for invoking models that require input file(s), the inference process will involve 3 steps:

Initializing the Request: this involves making an initial call to generate a RequestId
Uploading Input Files: this involves uploading the files for the RequestId
Invoking Inference: this step starts the inference process for a particular RequestId

The sections below outline these steps.

1. Request Initialization

You can initialize the request by making a POST against the initialize endpoint for the particular Model Id

shell

curl --request POST --url https://api.prod.unitypredict.com/api/predict/initialize/{model-id} \
--header 'Authorization: Bearer APIKEY@{yourApiKey}'

Request Parameters

model-id: The unique model Id of the model that is to be called. This appears in the url/address bar and can also be copied using the copy icon next to the predict button on the inference page (see screenshot below).
yourApiKey: The API key value that you have created on the Profile page of your UnityPredict account.
The json body needs to contain the following fields:
- InputValues: a key-value map of the input variables
- DesiredOutcomes: list of output variable names that you want to get back from the model

Sample Response JSON

json

{
    "contextId": "unitypredict-context-uuid",
    "requestId": "unitypredict-request-uuid",
    "errorMessages": null,
    "logMessages": null,
    "computeTime": "00:00:00",
    "computeTimeCharged": "00:00:00",
    "computeCost": 0.0,
    "outcomeValues": {},
    "outcomes": {},
    "status": "Processing"
}

Response Parameters

requestId: A unique identifier of this particular inference. This will be used for subsequent file uploads and API calls.

Response Codes

Response Code	Short Description	Long Description
200	Success	The request was successful.
400	Bad Request	The request was invalid.
401	Unauthorized	Authentication of the API key failed.
403	Forbidden	Access denied.
404	Not Found	The resource was not found.
500	Internal Server Error	An unexpected error occurred on the server.

2. Uploading Files

Uploading input files will be a two step process:

Get a public upload link for a specific file against a specific Request Id
Use returned uploadLink attribute from step 1 to perform a PUT operation for the file content. UnityPredict allows files up to 5GB to be uploaded.

Note: both of the above steps need to be repeated for every required input variable with File data type/

Getting the public upload link

To be able to upload a file, you need to generate a temporary, pre-signed upload link. This link is attached to your specific Request Id.

Sample Request Parameters

shell

curl --request GET --url https://api.prod.unitypredict.com/api/predict/upload/{request-id}/{upload-file-name.ext} \
--header 'Authorization: Bearer APIKEY@{yourApiKey}'

Request Parameters

request-id: The unique request identifier from the response of the initialize endpoint
upload-file-name.ext: Name of the file that you want to upload

Sample Response Json

json

{
    "uploadLink": "file-upload-link",
    "fileName": "unitypredict_generated_filename"
}

Response Parameters

uploadLink: Link which can be used to perform a PUT operation to upload your file.
fileName: Generated filename that will be used as the input variable value when invoking the predict endpoint in step 3.

Response Codes

Response Code	Short Description	Long Description
200	Success	The request was successful.
400	Bad Request	The request was invalid.
401	Unauthorized	Authentication of the API key failed.
403	Forbidden	Access denied.
404	Not Found	The resource was not found.
500	Internal Server Error	An unexpected error occurred on the server.

Uploading the file content

To upload the actual file content, you can simply use a PUT operation against the uploadLink retrieved in the previous step.

Sample Request Parameters

shell

curl --request PUT --url {uploadLink}  \
--header 'Content-Type: application/octet-stream'

Important Parameters

uploadLink: uploadLink URL from the previous step
Content-Type: application/octet-stream: Binary stream of the file to be uploaded

Response Codes

Response Code	Short Description	Long Description
200	Success	The request was successful.
400	Bad Request	The request was invalid.
401	Unauthorized	Authentication of the API key failed.
403	Forbidden	Access denied.
404	Not Found	The resource was not found.
500	Internal Server Error	An unexpected error occurred on the server.

3. Predict with Request Id

Once all the input files are uploaded using the procedure in step 2, you can invoke the predict endpoint for the particular Request Id by passing the Request Id in the url. You will need to make sure that the value of the variables with File data type matches the unitypredict_generated_filename returned by the upload endpoint (Step 2.1). The rest of the operations for inference is exactly the same as the regular predict REST calls.

shell

curl --request POST --url https://api.prod.unitypredict.com/api/predict/{model-id}/{request-id} \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer APIKEY@{yourApiKey}' \
--data '{
    "InputValues": {
        "Input File": `unitypredict_generated_filename`,
    },
    "DesiredOutcomes": [
        "Label"
    ]
}'

Request Parameters

model-id: The unique model Id of the model that is to be called. This appears in the url/address bar and can also be copied using the copy icon next to the predict button on the inference page (see screenshot below).
request-id: The unique request identifier generated in step 1.
yourApiKey: The API key value that you have created on the Profile page of your UnityPredict account.
The json body needs to contain the following fields:
- InputValues: a key-value map of the input variables
- DesiredOutcomes: list of output variable names that you want to get back from the model

Sample Response JSON

json

{
    "contextId": "unitypredict-context-uuid",
    "requestId": "unitypredict-request-uuid",
    "errorMessages": "",
    "computeTime": "00:00:02.4778178",
    "computeTimeCharged": "00:00:02.4778190",
    "computeCost": 0.0002477819,
    "outcomes": {
        "Label": [
            {
                "dataType": "Boolean",
                "probability": 0.015924746,
                "value": false
            }
        ]
    },
    "status": "Completed"
}

Response Parameters

contextId: A unique Id that is linked to the user session. If the model support 'Context' (ex. ChatBots), sending the same contextId on the next predict call will make sure that the model has access to the previous history of inferences from the same context.
requestId: A unique identifier of this particular call. This can be used to check the status of inference in long-running jobs.
status: Returns the inference status (see below). If this value is returned as Processing, it means the model needs more time to complete inference (see status API section).
errorMessages: Any error messages that happened during inference.
computeTime: Total run time for inference.
computeTimeCharged: Amount of compute time actually charged. For some more optimized models, this value can be shorter than computeTime
computeCost: Total cost of inference. This is charged to the account linked to the API key used for making the call.
outcomes: Contains the output values and probabilities (if provided by the model). Note: some models return multiple values for a single variable.

Response Codes

Response Code	Short Description	Long Description
200	Success	The request was successful.
400	Bad Request	The request was invalid.
401	Unauthorized	Authentication of the API key failed.
403	Forbidden	Access denied.
404	Not Found	The resource was not found.
500	Internal Server Error	An unexpected error occurred on the server.

Status Codes

Status	Status Description
"Completed"	Engine has successfully completed its execution
"Error"	Engine has faced errors during execution. Check `errorMessages` for error details
"Processing"	Engine is still processing the prediction
None	No status from Engine detected. Possibly due to server errors

API Invocation Using UnityPredict Python Package

To make it easier to invoke models on UnityPredict, you can use the unitypredict pip package. The following guide provides instructions on how to use this package.

Installation

shell

pip install unitypredict

Usage

Initializing the UnityPredict Client

To initialize a UnityPredictClient instance, simply provide your API key.

python

from unitypredict import UnityPredictClient
    
client = UnityPredictClient(apiKey="YourUnityPredictAPIKey")

Running Inference

There are two different ways you can perform inference:

Synchronous: Blocking operation using the predict function of the UnityPredict Client. This is idea for small models that have fast response times.
Asychronous: Non-Blocking operation that will invoke the model and return control back to the caller with a RequestId that can be used for checking the status of a job.

Synchronous Inference

python

response: UnityPredictResponse = client.Predict('TargetUnityPredictModelId', UnityPredictRequest(
    InputValues = {
        'Age': 20,
        'Chol': 207
    },
    DesiredOutcomes = ['Label'], 
    OutputFolderPath = "path/to/desired/output/folder" ))

Asynchronous Inference

python

response: UnityPredictResponse = client.AsyncPredict('TargetUnityPredictModelId', UnityPredictRequest(
    InputValues = {
        'Input File': LocalFile("path/to/myFile.txt"),
        'Language': 'English'
    },
    DesiredOutcomes = ['OutputFile'], 
    OutputFolderPath = "path/to/desired/output/folder" ))

# Check status of the job and get the results if it is Completed
response: UnityPredictResponse = client.GetRequestStatus(response.RequestId, outputFolderPath="path/to/desired/output/folder")

NOTE:

In order to upload a local file for inference, the file path should be mentioned under the format: LocalFile("path/to/myFile.txt").

Full Example

python

import time, sys
from unitypredict import UnityPredictClient, UnityPredictRequest, UnityPredictResponse, UnityPredictFileTransmitDto, UnityPredictFileReceivedDto, LocalFile
    

client = UnityPredictClient(apiKey="YourUnityPredictAPIKey")
request = UnityPredictRequest(
    InputValues = {
        'Input File': LocalFile("path/to/myFile.txt"),
        'Language': 'English'
    },
    DesiredOutcomes = ['OutputFile'], 
    OutputFolderPath = "path/to/desired/output/folder" )

response: UnityPredictResponse = client.AsyncPredict('TargetUnityPredictModelId', request)

if response.Status == None:
    print (f"Error: {response.ErrorMessages}")
    sys.exit(0)

# NOTE: This is a sample only. DO NOT make loops like this (they can become infinite loops if the job fails)!
maxtimeout = 30 # seconds
timeout = 0.5 # seconds
while response.Status != 'Completed':
    # Check status of the job and get the results if it is Completed
    response: UnityPredictResponse = client.GetRequestStatus(response.RequestId, outputFolderPath=request.OutputFolderPath)
    if response.Status == 'Completed':
        break
    print (f"Waiting for {timeout} seconds ...")
    time.sleep(timeout)
    timeout = min(2*timeout, maxtimeout)

for keys in request.DesiredOutcomes:
    for outcome in response.Outcomes.get(keys, []):
        dataType = outcome.get("dataType", None)
        if dataType == None:
            continue
        if dataType == "File":
            fileDetails: UnityPredictFileReceivedDto = outcome.get("value", None)
            if fileDetails == None:
                continue
            print (f"File: {fileDetails.FileName}, Path: {fileDetails.LocalFilePath}")
        
        else:
            value = outcome.get("value", None)
            prob = outcome.get("probability", None)
            print (f"Value: {value}, Probability: {prob}")


print (f"Error: {uptResponse.ErrorMessages}")
print (f"Cost: ${uptResponse.ComputeCost}")

UnityPredict API ​

Introduction ​

API Invocation for Models without Input Files ​

Sample Predict Endpoint API Call ​

Request Parameters ​

Sample Response JSON ​

Response Parameters ​

Response Codes ​

Status Codes ​

Checking Status of Long-Running Inferences ​

Request Parameters ​

Response Parameters ​

Response Codes ​

Downloading Generated Output File(s) ​

Request Parameters ​

Response Codes ​

API Invocation for Models with Input Files ​

1. Request Initialization ​

Request Parameters ​

Sample Response JSON ​

Response Parameters ​

Response Codes ​

2. Uploading Files ​

Getting the public upload link ​

Sample Request Parameters ​

Request Parameters ​

Sample Response Json ​

Response Parameters ​

Response Codes ​

Uploading the file content ​

Sample Request Parameters ​

Important Parameters ​

Response Codes ​

3. Predict with Request Id ​

Request Parameters ​

Sample Response JSON ​

Response Parameters ​

Response Codes ​

Status Codes ​

API Invocation Using UnityPredict Python Package ​

Installation ​

Usage ​

Initializing the UnityPredict Client ​

Running Inference ​

Synchronous Inference ​

Asynchronous Inference ​

Full Example ​

UnityPredict API

Introduction

API Invocation for Models without Input Files

Sample Predict Endpoint API Call

Request Parameters

Sample Response JSON

Response Parameters

Response Codes

Status Codes

Checking Status of Long-Running Inferences

Request Parameters

Response Parameters

Response Codes

Downloading Generated Output File(s)

Request Parameters

Response Codes

API Invocation for Models with Input Files

1. Request Initialization

Request Parameters

Sample Response JSON

Response Parameters

Response Codes

2. Uploading Files

Getting the public upload link

Sample Request Parameters

Request Parameters

Sample Response Json

Response Parameters

Response Codes

Uploading the file content

Sample Request Parameters

Important Parameters

Response Codes

3. Predict with Request Id

Request Parameters

Sample Response JSON

Response Parameters

Response Codes

Status Codes

API Invocation Using UnityPredict Python Package

Installation

Usage

Initializing the UnityPredict Client

Running Inference

Synchronous Inference

Asynchronous Inference

Full Example