[+]
Getting Started
[-]
Recognition
 [+]
Brain Training Beginner's Guide
 [+]
Recognition Documentation
  
  
 [-]
APIs
   
   
[+]
Detection
[+]
Segmentation
[+]
Resources
Updated on 9/11/2019
Brain Builder Knowledge Base
Inference API and SDK
Direct link to topic in this publication:
  • Recognition
  • »
  • APIs
  • »
  • Inference API and SDK

On This Page:

Inference API

Neurala's Inference API lets you pass images into your Staging and Production Brains and get the Brain's prediction as a response.

The API URL has the following structure:

https://brainbank.neurala.com/api/v1/inference/[brain-identifier]/[staging|production]

The API call requires the following inputs:

Brain Identifier

Your Brain is assigned a unique Brain Identifier that is available on the Publish screen. Use this Brain ID when making API calls.

API Key

API Keys are managed on the API Key Screen in the Administration section.

You can include the API Key as an authorization header or a query string parameter.

Authorization Header
curl --header 'Authorization: NeuralaAPIKey [YourApiKey]'

Query String Parameter
/api/v1/inference/[brain-identifier]/[staging|production]?NeuralaAPIKey=[YourApiKey]

Environment

Use the Staging or Production variables in the API URL to specify whether you'd like to run inference against your Staging or Production Brain.

File Uploads

To submit images to the API, send a multi-part form upload with an array of images using the files parameter. We will return you a JSON response body with predictions, matching to the image filename in each prediction.

  • You should make sure your images have unique file names.
  • The API supports jpg, png, gif, webp, tiff, and svg image types.
  • Users on a paid plan can run predictions in batches
  • Users on paid plan can upload zip files containing images. We will extract the images automatically

Code Example

cURL
curl -X POST \\
-H 'authorization: NeuralaAPIKey [YourApiKey]' \\
-F 'files=@/path/to/image1.jpg' \\
-F 'files=@/path/to/image2.jpg' \\
-F 'files=@/path/to/archive.zip' \\
https://brainbank.neurala.com/api/v1/inference/[brain-identifier]/[staging|production]

API Responses

All requests will return a JSON response. If the success property is true then you should have predictions, otherwise something went wrong. If the HTTP status code is 400 then it is most likely an invalid request, and a status code of 500 indicates a server-level error.

Your first request might take several seconds, but afterwards you can expect single-image requests to take less than 500ms or so.

Success (HTTP 200 Status)

{
"success": true,
"predictions": [
{
"image": "304452-equipment.jpg",
"results": [
{
"name": "Tractor",
"probability": 0.3395032584667206
},
{
"name": "Dump Truck",
"probability": 0.3381641209125519
},
{
"name": "Bulldozer",
"probability": 0.32233259081840515
}
]
},
{
"image": "tractor.jpg",
"results": [
{
"name": "Tractor",
"probability": 1
}
]
}
]
}

The success response includes a few different elements:

  • Success: true — Indicates the images were processed successfully.
  • Predictions — The array that contains all images and predictions.
    • Image — The file name of the image(s) that were submitted to the API.
    • Results — For each image, an array containing any predictions returned by the Brain.
      • Name — The Class name for the prediction.
      • Probability — A score between 0-1 representing how likely the Brain considers its prediction to be.

If the Brain returns multiple predictions, the higher probability score indicates that the Brain thinks there is a greater likelihood that prediction is correct. If predictions have similar probability scores, that indicates the Brain is uncertain as to which prediction is correct.

Invalid API Key (HTTP status 400)

Either your NeuralaAPIKey header was formatted incorrectly or your API Key is invalid.

{
"success": false,
"message": "The Authorization header is invalid or missing",
"code": "INVALID_AUTHORIZATION_HEADER"
}

Invalid image type (HTTP status 400)

The file type you are uploading is not valid. See the valid file types above.

{
"success": false,
"message": "doc.pdf was not a valid type",
"code": "INVALID_FILE"
}

No files were found (HTTP status 400)

We were unable to detect any file uploads in your request.

{
"success": false,
"message": "No files were found",
"code": "INVALID_FILE"
}

Invalid environment specified (HTTP status 400)

The API only runs inference for Staging and Production releases of your Brain.

{
"success": false,
"message": "Invalid environment: not-staging",
"code": "INVALID_PARAMETER"
}

Brain release not found (HTTP status 400)

The API will only run predictions on Brains that have been deployed to a Staging or Production environment.

{
"success": false,
"message": "Could not find release for brain 52fa8263-2e56-480c-98a9-5ac87da49c08 in environment staging",
"code": "BRAIN_RELEASE_NOT_FOUND"
}

Brain not found (HTTP status 400)

No Brain with the specified Brain identifier was found.

{
"success": false,
"message": "The requested brain was not found",
"code": "BRAIN_NOT_FOUND"
}

Timeout (HTTP status 500)

The API failed to complete your request in a reasonable amount of time.

{
"success": false,
"message": "Internal Server Error",
"code": "TIMEOUT_ERROR"
}

Capacity reached (HTTP status 400)

You have reached your limit on the number of API calls you are allowed in the current period. Please contact your account manager or support@neurala.com for assistance.

{
"success": false,
"message": "You have reached the allowable limit of this feature for your account",
"code": "CAPACITY_REACHED"
}

Monitoring API Usage

A summary of your API usage is displayed on the Brain Builder Dashboard, and more detail can be found on the API Analytics page, in the user menu drop-down. On the API Analytics page, you can view API usage by API Key, Brain, and Production/Staging environments.

SDK

Brain Deployment via Linux SDK currently available. Full documentation for the Linux SDK is available here.

SDK support for iOS and Android is coming soon. Watch this space for more details or reach out to us at support@neurala.com with any questions.

Next: Training API >>