APIs – your technical interface to Capice capice.ai

All of the Capice platform is accessible via the user interface at www.capice.ai and is also ready for you to use in your own software development project via the API interface. Capice.ai and the Capice iPhone app were built using these APIs. They work. That means you can build machine mearning in to your own application with very little development effort ! Good stuff…

Typically you will create your machine learning models in the user interface of the web application. It is very easy to do and takes minutes. Once you have the data in hand that you want to use as training.

If you choose to make use of it, the API access is via REST services and makes use of JSON payload formats as well as multi-part form data (for file transfers) for input. All returned values are in JSON formats. For example: {“ID” : “123”, “Name”: “abc” }

The APIs you will most frequently use are Sign In, Sign Out, Run Model (for image, line of text, text file, audio, linear regression on a single item, linear regression on a file), Run chain on an image, Get a model list or retrieve messages in your mailbox

Sign In

To use the APIs, first sign in to capice.ai using the credentials you created when you registered.

Request

URI: https://authentication-prod.capice.ai/v1/users/sign-in

JSON Key Type Required
email
The email used when you registered		 String Required
password
The password used when you registered		 String Required

Request Example

curl -H 'Content-type: application/json' -d '{"email":"testuser@gmail.com", "Password": "mypassword"}'
https://authentication-prod.capice.ai/v1/users/sign-in -X POST

Response

On success JSON is returned with key value of status set to OK. A return value set to Error indicates an error authenticating and the JSON error value contains the error reason. 3 failed attempts in a row locks the account for 1 hour.

1. {"status":"OK","data":{"FirstName":"aaa","LastName":"bbb"}}
2. {"status":"NOTFOUND"} 

Sign Out

When you are done using the API interface Sign Out. You will automatically be signed out if idle for 60 minutes.

Request

URI: https://authentication-prod.capice.ai/v1/users/sign-out

JSON Key Type Required
email
The email used when you registered		 String Required

Request Example

curl -H 'Content-type: application/json' -d '{"email":"testuser@gmail.com"}'
https://authentication-prod.capice.ai/v1/users/sign-out -X POST

Response

On success JSON is returned with value of status set to OK. A return value set to Error indicates an error signing out and the JSON error value contains the error reason.

1. {"status":"OK"} 

Classify an image

Use file types BMP, JPEG or GIF. But no animated GIFs. Use a published model or one you have created. It will classify an image file and return a JSON result. Since this is processing a file, use input type of multi part form data – not JSON.

Request

URI: https://run-model-prod.capice.ai/v1/models/image/file

JSON Key Type Required
email
The email used when you registered		 Multi-part form data: String Required
ID
The trained image model ID – one of yours or a community model		 Multi-part form data: String Required
filename
The contents of the image file to classify – just one image can be specified		 Multi-part form data: Integer data bytes Required

Request Example

curl -F "filename=@ImageToClassify.jpg" -F 'email=testuser@gmail.com' -F 'ID=123'
https://run-model-prod.capice.ai/v1/models/image/file -X POST

Response

On success JSON is returned with value of status set to OK and the classification result is JSON data element. The result is three part. “A return value set to Error indicates an error running the model and the JSON error value contains the error reason. The data results are a confidence value and three result values starting with the most likely.

The count value indicates how many images were processed. In the event classification was on a video stream with multiple frames (images) this will be the number of frames processed.

1. {"status": "OK", "data": {"confidence": "low - top 2 are very close", "result1": "most likely", "result2": 
"next most likely", "result3": "next most likely"}, "count": 1}
2. {"status":"OK","data":{"confidence":"Image may not be for this model","result1":"most likely","result2":
"next most likely","result3":"next most likely"}, "count" : 1}
3. {"status": "Error", "error": "File is not an image file"}
4. {"status":"Error","error":"Not an an Image ID"}

Classify a video stream

Use file types MP4 or AVI. Use a published model or one you have created. It will classify a video stream – frame by frame, and return a JSON result. Since this is processing a file, use input type of multi part form data – not JSON.

Request

URI: https://run-model-prod.capice.ai/v1/models/video/file

JSON Key Type Required
email
The email used when you registered		 Multi-part form data: String Required
ID
The trained image model ID – one of yours or a community model		 Multi-part form data: String Required
filename
The contents of the video to classify		 Multi-part form data: Integer data bytes Required

Request Example

curl -F "filename=@VideoToClassify.jpg" -F 'email=testuser@gmail.com' -F 'ID=123'
https://run-model-prod.capice.ai/v1/models/video/file -X POST

Response

On success JSON is returned with value of status set to OK and the classification result is JSON data element. A return value set to Error indicates an error running the model and the JSON error value contains the error reason. The data results are a set of classifications – frame by frame.

The count value indicates how many images were processed. For video classification with multiple frames (images) this will be the number of frames in the video.

1. {"status": "OK", "data": [ "frame1", "frame2", "frame3"], "count": 3}
3. {"status": "Error", "error": "File is not video file"}
4. {"status":"Error","error":"Not an an Image ID"}

Classify a line or paragraph of text

The text input can be as long as want and will result in a single classification. Run this on a published model or one you have created. It will classify text that you provide and return the result.

Request

URI: https://run-model-prod.capice.ai/v1/models/text/one/

JSON Key Type Required
email
The email used when you registered		 String Required
ID
The trained text model ID – one of yours or a community model		 String Required
Text
The text to classify		 String Required

Request Example

curl -H 'Content-type: application/json' -d '{"email":"testuser@gmail.com", "ID": "123", "Text":"Classify this text"}'  \
https://run-model-prod.capice.ai/v1/models/text/one -X POST

Response

On success JSON is returned with value of status set to OK and the classification result is JSON data element. A return value set to Error indicates an error running the model and the JSON error value contains the error reason. count for a single classification will always be 1.

1. {"status": "OK", "data": {"confidence": "high", "result1": "Classification #1", "result2": "Classification #2",
 "result3": "Classification #3"}, "count": 1}
2. {"status": "Error", "error": "Model not found"}
3. {"status":"Error","error":"Invalid JSON request format"}

Classify an entire file of text

Classify a plain text file – row by row. The response will be a classification per row. This enables you to run many classifications at once. Run this on a published model or one you have created. It will classify text that you provide and return the result.

Request

URI: https://run-model-prod.capice.ai/v1/models/text/one

JSON Key Type Required
email
The email used when you registered		 String Required
ID
The trained text model ID – one of yours or a community model		 String Required
File
The contents of the file to classify. Each row seperated by a newline character.		 Multi-part form data Required

Request Example

curl -F "filename=@TextFileToClassify.csv" -F 'email=testuser@gmail.com' -F 'ID=1018'  \
https://run-model-prod.capice.ai/v1/models/text/file -X POST

Response

On success JSON is returned with value of status set to OK and the classification result is JSON data element. A return value set to Error indicates an error running the model and the JSON error value contains the error reason. In the file to run, use the exact same format as the training file — except no ground truth column. count value will be the number of rows in the inference file and the size of the returned array of inferences.

1. {"status": "OK", "error": "", "data": [["Classification for line 1", "line 1 input string"], 
["Classification for line 2", "line 2 input string"]], "count" : 2}

 

Numeric prediction on one item

Numeric prediction predicts a numeric value as opposed to classification (such as what will be the sales price of my home) from a numeric set of feature data. Run this on a published model or one you have created. It will perform numeric prediction based on the features in the training model.

Request

URI: https://run-model-prod.capice.ai/v1/models/linear/one

JSON Key Type Required
email
The email used when you registered		 String Required
ID
The trained numeric prediction model ID – one of yours or a community model		 String Required
Text
The numeric prediction values. A single line of comma separated values. These are the features as in the training file		 String Required

Request Example


curl -H 'Content-type: application/json' -d '{"email":"testuser@gmail.com", "ID": "123", "Text":"1,2,3,4"}' \
https://run-model-prod.capice.ai/v1/models/linear/one -X POST

Response

On success JSON is returned with value of status set to OK and the numeric prediction result is JSON data. A return value set to Error indicates an error running the model and the JSON error value contains the error reason. count for a single classification will always be 1..

1. {"status": "OK", "data": "8,304.42", "count": 1}
2. {"status": "Error", "error": "This numeric prediction model expects 4 features and 3 were supplied."}
3. {"status": "Error", "error": "Model not found"}
4. {"status":"Error","error":"Invalid JSON request format"} 

Numeric prediction on a file

Classify an entire CSV file of numeric prediction data – row by row. Each row in the CSV file is a single set of features to use for inference. Use this to run a large batch of numeric predictions. This predicts a CSV file that you provide and returns CSV file as result. Since this is processing a file, use input type of multi part form data – not JSON.

Request

URI: https://run-model-prod.capice.ai/v1/models/linear/file

JSON Key Type Required
email
The email used when you registered		 String Required
ID
The trained numeric prediction model ID – one of yours or a community model		 String Required
File
The numeric prediction values. Multiple rows with comma separated values. Each row seperated by newline character. Each row has the same features as in training.		 Multi-part form data Required

Request Example

curl -F "filename=@FileToClassify.txt" -F 'email=testuser@gmail.com' -F 'ID=123' \
https://run-model-prod.capice.ai/v1/models/linear/file -X POST

Response

On success JSON is returned with value of status set to OK and the classification result is JSON data element. A return value set to Error indicates an error running the model and the JSON error value contains the error reason. Use same format for the inference data as was used for the training file except no ground truth column. count value will be the number of rows in the inference file and the size of the returned array of inferences.

1. {"status": "OK", "data": ["2500.1", "2700.2"], "count": 2}
2. {"status": "Error", "error": "All rows must have same number of features. row 2 has 4 and not 3"}
3. {"status": "Error", "error": "This numeric prediction model expects 4 features and 3 were supplied."}

 

Numeric classification on one item

Takes numeric feature data input and classifies it. Run this on a published model or one you have created. It will perform numeric classification based on the features in the training model.

Request

URI: https://run-model-prod.capice.ai/v1/models/numeric-classification/one

JSON Key Type Required
email
The email used when you registered		 String Required
ID
The trained numeric classifictaion model ID – one of yours or a community model		 String Required
Text
The numeric classification inference values. A single line of comma separated values. These are the same features as in the training file		 String Required

Request Example

curl -H 'Content-type: application/json' -d '{"email":"testuser@gmail.com", "ID": "123", "Text":"1,2,3"}' \
https://run-model-prod.capice.ai/v1/models/numeric-classification/one -X POST

Response

On success JSON is returned with value of status set to OK and the numeric classification result is JSON data. A return value set to Error indicates an error running the model and the JSON error value contains the error reason. count for a single classification will always be 1. probability is an indicator of how sure the result is.

1. {"status": "OK", "data": "classification", "probability": "100.0", "count": 1}
2. {"status": "Error", "error": "This numeric data model expects 10 features and you supplied 1"}
3. {"status": "Error", "error": "Model not found"}
4. {"status":"Error","error":"Invalid JSON request format"}

 

Numeric classification on a file

Classify an entire CSV file of feature data – row by row. Each row in the CSV file will receive a single set of values to predict. Use this to run a large batch of numeric classifications. This classifies a CSV file that you provide and returns CSV file as result. Since this is processing a file, use input type of multi part form data – not JSON.

Request

URI: https://run-model-prod.capice.ai/v1/models/numeric-classification/file

JSON Key Type Required
email
The email used when you registered		 String Required
ID
The trained numeric classification model ID – one of yours or a community model		 String Required
File
The numeric classification inference values. Multiple rows with comma seperated values. Each line sperated by a newline character. Every row has the same features as in the training file		 Multi-part form data Required

Request Example


curl -F "filename=@FileToClassify.txt" -F 'email=testuser@gmail.com' -F 'ID=123' \
https://run-model-prod.capice.ai/v1/models/linear/file -X POST

Response

On success JSON is returned with value of status set to OK and the classification result is JSON data element. A return value set to Error indicates an error running the model and the JSON error value contains the error reason. In the file to run, use the exact same format as the training file — except no ground truth. That means each row starts with a comma. We are going to fix this in our next release to eliminate need for the leading comma. Use same format for the inference data as was used for the training file except no ground truth column. probability” is an indicator of how sure the result is. source is a row by row representation of the input data.

1. {"status": "OK", "data": ["Class A", "Class B", "Class C", "Class B"], "probability": [ "90.0", "100.0", 
"99.2", "98.0"],  
                    "source": ["1","2"], ["5", "1"], ["8","2"], ["2","2"],"count": 4}
2. {"status": "Error", "error": "linear regression file requires same number of features as training set"}

Numeric binary classification on one item

Numeric binary classification inference is returned as is ‘in’ or ‘out’ of the tarined data set. Run this on a published model or one you have created. It will perform numeric binary classification based on the features in the training model.

Request

URI: https://run-model-prod.capice.ai/v1/models/binary/one

JSON Key Type Required
email
The email used when you registered		 String Required
ID
The trained binary classification model ID – one of yours or a community model		 String Required
Text
The binary classification inference values. A single line of comma separated values. These are the same features as in the training file		 String Required

Request Example

curl -H 'Content-type: application/json' -d '{"email":"testuser@gmail.com", "ID": "123", "Text":"1,2,3,4,5"}' \
https://run-model-prod.capice.ai/v1/models/binary/one -X POST

Response

On success JSON is returned with value of status set to OK and the binary classification result is JSON data. A return value set to Error indicates an error running the model and the JSON error value contains the error reason. countfor a single binary classification will always be 1.

1. {"status": "OK", "data": "Passed", "count": 1}
1. {"status": "OK", "data": "Failed", "count": 1}
3. {"status": "Error", "error": "This binary classification model expects 21 features and you supplied 5"}
4. {"status":"Error","error":"Invalid JSON request format"}

Numeric binary classification on a file

Classify an entire CSV file of binary classifications – row by row. Binary Classification returns the reult of “in the data set” or “outside the data set” but does this via a high dimensional wrapper around all the training data. So it is a not a simple algorithm of ‘less than” or “greater than”. Each row in the CSV file is a set of values to predict. Use this to run a large batch of binary classifications. This classifies a CSV file that you provide and returns CSV file as result. Since this is processing a file, use input type of multi part form data – not JSON. Use same format for the inference data as was used for the training file except no ground truth column.

Request

URI: https://run-model-prod.capice.ai/v1/models/binary/file

JSON Key Type Required
email
The email used when you registered		 String Required
ID
The trained binary classification model ID – one of yours or a community model		 String Required
File
The binary classification inference values. A single line of comma separated values. Each rowis seperated by a newline character. Every rows has the same features as in the training file.		 Multi-part form data Required

Request Example

curl -F "filename=@FileToClassify.txt" -F 'email=testuser@gmail.com' -F 'ID=123' \
https://run-model-prod.capice.ai/v1/models/binary/file -X POST

Response

On success JSON is returned with value of status set to OK and the classification result is JSON data element. A return value set to Error indicates an error running the model and the JSON error value contains the error reason. count value will be the number of rows in the inference file and the size of the returned array of inferences.

1. {"status": "OK", "data": [ "Passed", "Failed", "Passed], "count": 3}
2. {"status": "Error", "error": "This binary classification model expects 21 features and you supplied 5"}

Classify audio

Use only file type of WAV format. Audio stream inference can be long, or an single, individual audio clip of less than 10 seconds. Run this on a published model or one you have created. It will perform numeric binary classification based on the features in the training model.

Request

URI: https://run-model-prod.capice.ai/v1/models/audio/file

JSON Key Type Required
email
The email used when you registered		 String Required
ID
The trained audio model ID – one of yours or a community model		 String Required
audioStreamMode
How to process the audio file. Omit the parameter and the file is assumed to be less than ten seconds and require one inference. 10 will take a much larger file and will process in 10 second chunks returning the result for each audio segment. If silence, the system will locate the audio in between silence, and return classifications. silence also supports large audio files.		 String Optional
Text
The audio file data to process		 String Required

Request Example

curl -F "filename=@AudioFileToClassify.wav" -F 'email=testuser@gmail.com' -F 'ID=123' \
https://run-model-prod.capice.ai/v1/models/audio/file -X POST

curl -F "filename=@AudioFileToClassify.wav" -F 'email=testuser@gmail.com' -F 'ID=123' -F 'audioStreamMode=silence' \
https://run-model-prod.capice.ai/v1/models/audio/file

Response

On success JSON is returned with value of status set to OK and the audio classification result is JSON data. A return value set to Error indicates an error running the model and the JSON error value contains the error reason. For audio streams that do not use the audioStreamMode parameter, the audio is parsed to locate the complete list of sounds and the timestamp of each sound thta was classified is also returned.

1. {"status": "OK", "timestamps": ["0.7-2.00", "5.0-7.45", "25.9-33.2"], "data": ["car horn", "glass breaking", 
"car engine"], "count": 3}
2. {"status": "OK", "data": {"confidence": "Audio may not be for this model", "result1": "1", "result2": "4", 
"result3": "3"}, "count": 1}
3. {"status": "OK", "data": {"confidence": "High", "result1": "1", "result2": "4", "result3": "3"}, "count": 1}

Chain model inference on an image

Use types BMP, JPEG or GIF. But no animated GIFs. Use a published chain or one you have created. It will classify an image file through the chain and return a JSON result. Since this is processing a file, use input type of multi part form data – not JSON.

Request

URI: https://run-chain-prod.capice.ai/run-chain-file

JSON Key Type Required
email
The email used when you registered		 String Required
ID
The trained text model ID – one of yours or a community model		 String Required
File
The contents of the image file to classify		 Multi-part form data Required

Request Example

curl -F "filename=@ImageToClassify.jpg" -F 'email=testuser@gmail.com' -F 'ID=123' \
https://run-chain-prod.capice.ai/run-chain-file -X POST

Response

On success JSON is returned with value of status set to OK and the classification result is JSON data element. A return value set to Error indicates an error running the model and the JSON error value contains the error reason. The data results do not show a confidence value since chains are a series of model files being run where result1 feeds the next model file regardless of confidence.

1. {"status": "OK", "data": {"confidence": "chain", "result1": "classification1, classification2", "result2":"-",
"result3":"-"}}
2. {"status": "Error", "error": "File is not an image file"}
3. {"status":"Error","error":"Not an an Image ID"}

Get list of models

Get a list of models – published or private

Request

URI: https://upload-list-prod.capice.ai/v1/model-list

JSON Key Type Required
email
The email used when you registered		 String Required
Action
The type of list to be returned: AllMySuccesful, AllMyUploads, AllPublished		 String Required

Request Example

curl 'https://upload-list-prod.capice.ai/v1/model-list?email=testuser@gmail.com&Action=AllMySuccessful' -X GET

Response

On success JSON is returned with value of status set to OK and the classification result is JSON data array of values. A return value set to Error indicates an error running the model and the JSON error value contains the error reason.

1. {"status":"OK","data":[{" ID":1429,"Type":"Image", "Description":"Tomato Classification", "TrainingDate":"2019-09-
02T16:00:05.000Z", "UploadDate":"2019-09-02T15:57:31.000Z", "Size":496121, "Published":"N", "Status":"OK", "Rating":0,
 "Version":1, "NumberRatings":0, "Uses":7, "ModelFile":"Image1567439851109.Model", "ClassFile":"Image1567439851109.Class"
, "WordsFile":"","DateTime":"2019-09-02T16:00:05.000Z", "Result":"Training accuracy: 99.71 %, Validation accuracy:
85.06%, SVM accuracy: 98.56 / 97.70% / 0.00%", "Classes":"DoNotPick,Rotten,Ripe", "Records":62,"Features":null, 
"Resolution":56, "Alpha":0.001, "BatchSize":30, "MaxIterations":200, "TrainTest":0.8, "ProcessedRecords":434, 
"SVMGamma":0.001," SVMNu":0.001, "ActualIterations":20
2. {"status":"Error","error":"Invalid action"}
3. {"status":"Error","error":"Invalid JSON request format"}

Get mailbox messages

Get a list of your mailbox messages

Request

URI: https://mailbox-prod.capice.ai/GetList

JSON Key Type Required
email
The email used when you registered		 String Required

Request Example

curl https://mailbox-prod.capice.ai/GetList? email:aaa@gmail.com -X GET

Response

On success JSON is returned with value of status set to OK and the mailbox messages result is JSON data array of values. A return value set to Error indicates an error running the model and the JSON error value contains the error reason.


1. {"status":"OK","data":[{ "Sender":"user@gmail.com", "Message":"", "SendDate":"2019-03-21T13:17:03.000Z", "ID":123, "MasterID":456, "Version":1, "Description":"description of model", "Type":"Image", "Status":"Approved", "Sender":"Name of user"}, {"Sender":"aaa@gmail.com", "Message":"", "SendDate":"2019-03-26T12:06:38.000Z", "ID":124, "MasterID":457, "Version":1, "Description":"description of model;", "Type":"Image", "Status":"Rejected", "Sender":"Name of user"}]}