Welcome to Neurons Predict API Documentation

Here you will find examples to help you get started

Authentication

Your Neurons representative will provide you with an API key.
In order to authorize your API requests the API key must be provided in the "X-API-Key" header field.
If you misplace or lose your API Key, please contact us immediately so that we can provide you with a new one.
If you do not have a representative at Neurons yet, please contact: [email protected]

Webhooks

In order to configure webhooks so that you can integrate process completion notifications with your own backend,
please contact your Neurons representative and we will set you up right away.

The webhook POST request will always be formatted like so for images and video:

{
  "media_type":  "image/video",
  "media_id":    UUID4,
  "status":      "done/failed",
  "results": {
    "formatted": signed_url,
    "heat":      signed_url,
    "fog":       signed_url,
    "metrics":   signed_url
  }
}

and like so for AOIs:

{
  "media_type":  "aoi",
  "media_id":    UUID4,
  "status":      "done/failed",
  "results": {
    "aois": {
      "AOIName1": {
        "spec": aoi_coordinate_spec,
        "attentionpercent": percentage_of_attention
      },
      "AOIName2": {
        "spec": aoi_coordinate_spec,
        "attentionpercent": percentage_of_attention
      }
    }
  }
}

OpenAPI Specification

The OpenAPI specification JSON can be acquired here:

Images

Upload Image

To upload and process an Image simply use this endpoint:

Get Image Results/Status

You can then get the current status and results of your image process here:

List images

Or list your uploaded images here:

Image AOIs

Upload Image AOIs

You can add AOIs to an already uploaded image at this endpoint:

The JSON paylod must be structured like so:

{
  "aois": {
    "AOIName1" : {
      "points": [
        {"x": 0.0, "y": 0.0},
        {"x": 0.3234, "y": 0.2765},
        {"x": 0.2765, "y": 0.3234}
      ]
    },
    "AOIName2": {
      "points": [
        {"x": 0.0, "y": 0.0},
        {"x": 0.0, "y": 1.0},
        {"x": 1.0, "y": 1.0},
        {"x": 1.0, "y": 0.0}
      ]
    }
  }
}

It is important to note that all fields must be defined as floats (number with decimal point), and that the number must represent a fraction of the height/width of the image.

This means that the top left corner of the image will be defined like so:

{"x": 0.0, "y": 0.0}

the bottom right corner will be defined like so:

{"x": 1.0, "y": 1.0}

and the exact middle like so:

{"x": 0.5, "y": 0.5}

Get Image AOIs

To get the AOIs of an image (with the results, if they are ready) use the following endoint:

Videos

Upload video

Initiate Upload

To initiate a video upload use this endpoint:

The JSON response will contain a field "resumable_url", which is used as the upload target.

Upload Video

Upload your video with the provided "resumable_url" field (from the initialisation step), as described here:

Finalise Upload

Finalise your upload and start the processing at this endpoint:

Get Video Results/Status

Get the status/results of your uploaded video here:

List Uploaded Videos here:

Video AOIs

Upload Video AOIs

You can upload AOIs to an already existing video here:

The JSON paylod must be structured like so:

{
  "aois": {
    "AOIName1" : {
      "points": [
        {"x": 0.0, "y": 0.0},
        {"x": 0.3234, "y": 0.2765},
        {"x": 0.2765, "y": 0.3234}
      ],
      "seconds": 5.88
    },
    "AOIName2": {
      "points": [
        {"x": 0.0, "y": 0.0},
        {"x": 0.0, "y": 1.0},
        {"x": 1.0, "y": 1.0},
        {"x": 1.0, "y": 0.0}
      ],
     	"seconds": 10.0
    }
  }
}

The specification for the points is the same as for images.

Get Video AOIs

To get the AOIs of a video (with the results, if they are ready) use the following endoint:

Deletion

If you should desire to delete any uploaded content, you can do so at these endpoints:

Image

Image AOIs

Video

Video AOIs

Media (Video or Image)

Metrics (Consumption Statistics)

You can get the amount of processed images and video seconds for a given month at this endpoint: