NAV Navbar
cURL

Welcome

Welcome to Aiconix aingine API!

Here you can use the Aiconix aingine to access many different artificial intelligence providers on just one platform! You can convert speech to text, video to text, translate, perform face detection in images and many more awesome things, all with just a few clicks!

We currently have programming language bindings in cURL. More bindings are coming soon.

You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

If you have any questions, please don't hesitate to contact us, so we can help you.

Enjoy!

The Aiconix Dev Team

API Server

Please use the following server for all calls.

Environment URL
Production https://api.aiconix.cloud/v1

Features

Here you will find a list of our current available features. If you have any request for new features, please use the need help button on the left-hand navigation bar to mail us your request.

For Image

Feature Description
Brand Returns brand name found in the image.
Color Returns color shemes found in the image.
Content Moderation Categorization of explicit content e.g. adult, racy, medical, spoof, violence, etc.
Emotion Detection Classifies the emotion of the person in the image.
Face Detection Returns rectangles for found faces in the image.
Face Recognition Returns the name of the celebrities found in the image.
Faice Identification Returns an id for every face found in the image.
Facial Attributes Returns the analysis of the facial attributes detection in the image.
Hair Color Returns hair color on person found in the image.
Label Detection Returns a label shown in the image.
OCR Optical Character Recognition of the text in the image.
Emotion Detection Classifies the emotion of the person in the image.
Facial Landmarks Detection Returns facial landmarks (eyes, nose,...) for every person in the image.
Pose Detection Returns face, person, right hand and left hand for found person in the image.
Shot Size Returns how much of the scene is included in the picture.
Landmarks & Places Recognition Returns list of recognized places from picture with geo locations.

Supported File Extensions

For Audio

Feature Description
Speech To Text Transcripts the audio file into text.

Supported File Extensions

We support audio files up to 2048 MB (after conversion to .wav).

For Video

Feature Description
Block Detection Provides information about the found blocks in the video.
Content Moderation Categorization of explicit content e.g. violence, sexual, etc.
Emotion Detection Request detection of emotions on emotion polygons at certain time frames.
Face Detection Provides rectangles where faces are visible in the scene.
Face Recognition Returns the name of the celebrities.
Face Landmarks Detection Request the facial landmarks (eyeLeft, mouthRight, etc...) for each detected face of a video at a certain time frames.
Facial Attributes Returns the analysis of the facial attributes detection.
IAB Categories Request IAB Categories of a video at a certain time frame.
Keyword Detection Returns keywords mentioned in a time frame.
Label Detection Provides label of a segment in the video.
OCR Optical Character Recognition of text shown in the video.
Object Tracking Request object tracking of a video at a certain time frame.
Person Tracking Tracks the distinct persons in the video.
Shot Detection Provides information about the time when a scene changes.
Speech To Text Transcripts the audio track into text.
Facial Landmarks Detection Returns facial landmarks (eyes, nose,...) for every person in the image.

Supported File Extensions

We support video files up to 2048 MB.

For Text

We support only text analysis for texts up to 16 MB.

Feature Description
Topics and Categories Request the API to classify the given text.
Translation Returns input text translated into desired language.

Status Codes

For media type features which are called synchronously e.g. images and text.

Status Description
Initiated Call has been send to provider.
Success Call was successful and results are present.
Failed Call was not successful and no results are present.
Partial Only available when BestResults have been selected. Partial solution from responding providers can be calculated.

For media type features which are called asynchronously e.g. video and audio.

Status Description
Polling Waiting for results from provider.
Success Call was successful and results are present.
Timeout Call was unsuccessful due to provider timeout.
Failed Call was not successful and no results are present.
Partial Only available when BestResults have been selected. Partial solution from responding providers can be calculated.

Limitations

Following limitations apply for Aingine API

Limitations for Audio media type

Description Values
Supported extensions mp3, m4a, wav, flac, aiff, au, ogg, aac
Maximum file size 2048 MB

Limitations for Audio Subtitle generation

POST /cox/audio/{{requestId}}/subtitle/{{format}}

Description Values
Maximum Characters Per Line < 150 characters
Maximum Number Of Lines < 10
Minimum Caption Duration < 10 seconds

Limitations for Video media type

Description Values
Supported extensions mp4, mov, webm
Maximum file size 2048 MB

Limitations for Image media type

Description Values
Supported extensions jpg/jpeg, png, bmp and other Raster formats
Maximum file size 2048 MB
Maximum image resolution 15000 x 15000 pixels

Limitations for Text

Description Values
Supported extensions N/A
Maximum text size 100.000 characters

Upload Service

This service allows the user to upload files onto a secured data storage in order to speed up the reprocessing of media files.

First you need to authenticate with your aiconix credentials to receive an authentication token. Then you can upload, download or delete files from the storage.

Authentication

Example request

curl -X POST \
  https://api.aiconix.cloud/v1/auth \
  -H 'Content-Type: application/json' \
  -d '{
    "email":"email.address@provider.com",
    "password":"password"
}'

Example return in HEADER

Authorization -> Bearer laksdfj823jhlkfasdiJjYkBhaWNvbml4LmRlIiwiUk9MRVMivcml0eSI6

POST /auth

Description

Request an authentication (bearer) token to communicate with the server.

Body

Parameter Type Description
email string Your registered aiconix mail address
password string Your aiconix password

Response

The authorization bearer token is in the header of the response, not in the body.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Upload

Audio: Example request

curl -X POST \
  https://api.aiconix.cloud/v1/file/audio \
  -H 'Authorization: Bearer BEARER-TOKEN' \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'file=@C:\Users\cb\Desktop\api-data-samples\audio\h_orig.wav'

Video: Example request

curl -X POST \
  https://api.aiconix.cloud/v1/file/video \
  -H 'Authorization: Bearer BEARER-TOKEN' \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'file=@C:\Users\cb\Desktop\api-data-samples\video\SampleVideo_1280x720_1mb.mp4'

Example return

5c58982a9fbf77471c924819

POST /file/[audio | video]

Description

With this procedure you can upload an audio or video file to the online storage. Once the file is uploaded it will be converted such that our AI's can process it.

Header

Parameter Type Description
bearer Authorization Your bearer token from authentication call
file form-data File which shall be uploaded

Response

Parameter Type Description
fileId string Unique file identifier which is mapped to your account

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Process

Audio: Example request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/audio/processUploadedFile \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey" : "363080f0-f5fa-4eb0-a024-4314a825b183",
    "fileId" : "5c58982a9fbf77471c924819",
    "fileName" : "testAudioFile.wav"
}'

Video: Example request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/video/processUploadedFile \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey" : "363080f0-f5fa-4eb0-a024-4314a825b183",
    "fileId" : "5c58982a9fbf77471c924819",
    "fileName" : "testMovie.mp4"
}'

Audio and Video: Example return

8b582147-39bc-41e1-973d-ba3aba951513

POST /cox/[audio | video]/processUploadedFile

Description

With this procedure you can analyse a file which has been uploaded to the online storage. The behaviour is similar to the usual way of using our api.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page
fileID string The id from the upload call, so we know which file we need to process
fileName string You need to give your file a name, such that we process it further

Response

Parameter Type Description
requestID string Unique identifier which is mapped to your account

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Poll result

Example request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/video/994baed4-ff47-452f-8eb9-113c65750b02

Example return

[
    {
        "providers": [
            "Microsoft"
        ],
        "requestId": "994baed4-ff47-452f-8eb9-113c65750b02",
        "mediaType": "Video",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "shotResult": {
            "status": "Success",
            "shots": [
                {
                    "startTime": 200,
                    "endTime": 280
                }
            ]
        }
    }
]

GET /cox/[audio | video]/<requestID>

Description

With this procedure you can check the processing result for a video or audio file from the online storage. You need the requestID from your previous process call in order to poll the results of the analysis.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Details

Example request

curl -X GET \
  https://api.aiconix.cloud/v1/file/details
  -H 'Authorization: Bearer BEARER-TOKEN'

Example return

[
    {
        "id": "5d5a5e95139da8172d957e2a",
        "filename": "test.mp4",
        "uploadDate": "2019-08-19T08:32:24.430+0000",
        "size": 261096476
    }

    ...

    {
        "id": "5d5ab989139da82befa09c7a",
        "filename": "test.mp4",
        "uploadDate": "2019-08-19T15:00:28.714+0000",
        "size": 261096476
    }
]

GET /file/details

Description

Returns all still existing files (not yet removed) for particular user that uploaded them. Returned data: fileId, filename, uploadDate and size

Header

Parameter Type Description
bearer Authorization Your bearer token from authentication call

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Delete

Example request - get converted fileId

curl -X DELETE \
  https://api.aiconix.cloud/v1/file/994baed4-ff47-452f-8eb9-113c65750b02
  -H 'Authorization: Bearer BEARER-TOKEN'

DELETE /file/<fileID>

Description

In order to delete files from your file server use this command.

You can only delete file which you have uploaded, therefore you need to add your bearer token for authorization. Lastly you need to add the fileID which you want to delete.

Header

Parameter Type Description
bearer Authorization Your bearer token from authentication call

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Download Guide

This guide will step you through the usage of our api in order to download the file.

Example request

curl -X GET \
  https://api.aiconix.cloud/v1/file/converted?originalGridFsId=5d667612c99dcc1350689b42&mediaType=Video

1. Get converted file ID

In order to download the file, first we need to get converted fileId based on original fileId. Original fileId will be received after file upload.

curl -X GET -G \   https://api.aiconix.cloud/v1/file/converted \
-d 'originalGridFsId=5d667612c99dcc1350689b42' \
-d 'mediaType=Video'


If file exists converted fileId will be returned. In case that file doesn't exist, response will be 404 NOT FOUND.

 5d667613c99dcc1350689b5e

2. Download file

GET /file/<convertedFileId>

curl -X GET \   https://api.aiconix.cloud/v1/file/5d667613c99dcc1350689b5e

Description

Download your file from the server. It will return the file in binary format. Audio files are encoded as .wav and video files as .mp4.

Parameter

Parameter Type Description
fileID string The fileId received from first guide step (converted fileId)

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Limitations

Following limitations apply for Aingine Upload API

Limitations for Upload

Description Values
Maximum file size 2048 MB

Audio

Guide

This guide will step you through the usage of our api in order to transcribe an audio file into text.

1. Authenticate against the Upload Service

In order to communicate with the upload service we need to request a bearer token.

curl -X POST \
  https://api.aiconix.cloud/v1/auth \
  -H 'Content-Type: application/json' \
  -d '{
    "email":"email.address@provider.com",
    "password":"password"
}'

If successfully authenticated against our system you will receive in the header a bearer token , which will be used for further communication with the server.

Authorization -> Bearer laksdfj823jhlkfasdiJjYkBhaWNvbml4LmRlIiwiUk9MRVMivcml0eSI6

2. Upload an audio file

Now we want to upload a .wav file to the server. We do this by the following command.

curl -X POST \
  https://api.aiconix.cloud/v1/file/audio \
  -H 'Authorization: Bearer BEARER-TOKEN' \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'file=@C:\Users\cb\Desktop\api-data-samples\audio\h_orig.wav'

When successfully uploaded we receive a fileID from the server which is linked to our account.

5c58982a9fbf77471c924819

3. Generate an API key

Before we can process a file we need to configure an api key. Please go to config.aiconix.cloud and configure yourself a key for speech to text conversion. Copy the key from the page since we need it in the next step.

Slate guide audio

Available operation modes:

4. Initiate processing of file

Now we can initiate the processing of our uploaded file. We simply need to pass the currently configured apiKey, received fileID and a certain fileName with the matching audio file format.

curl -X POST \
  https://api.aiconix.cloud/v1/cox/audio/processUploadedFile \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey" : "363080f0-f5fa-4eb0-a024-4314a825b183",
    "fileId" : "5c58982a9fbf77471c924819",
    "fileName" : "testAudioFile.wav"
}'

After sending the request call we receive a process id.

4768f101-b4c6-40fc-95a5-7ab37dc9eaa1

5. Poll for request

With the before received processID we can poll for results.

curl -X GET \
  https://api.aiconix.cloud/v1/cox/audio/34c4166e-c960-433a-b0bc-3b85bdfc55e3

We need to poll since different providers process the files differently. You can see in the return field "processingFinished", which provider return already a result and which did not yet.

{
        "providers": [
            "aiconix"
        ],
        "requestId": "083739c6-47d0-4b15-a5ee-9892b9d96e81",
        "mediaType": "Audio",
        "operationMode": "BestResults",
        "processingFinished": false,
        "audioTranscriptionResult": {
            "status": "Polling",
            "featureError": "Result not ready..."
        }
}

6. Receive result

The processing is complete if all providers return true in their respective processingFinished flags.

[
    {
        "providers": [
            "aiconix"
        ],
        "requestId": "4768f101-b4c6-40fc-95a5-7ab37dc9eaa1",
        "mediaType": "Audio",
        "operationMode": "BestResults",
        "processingFinished": true,
        "audioTranscriptionResult": {
            "status": "Success",
            "transcript": "Who's what's these are I think I know his houses - in the village though.",
            "confidence": 0.7122456186865265,
            "words": [
                {
                    "value": "Whose",
                    "alternatives": [
                        {
                            "value": "Whose",
                            "confidence": 0.8
                        },
                        {
                            "value": "Who's",
                            "confidence": 0.2
                        }
                    ]
                },
                {
                    "value": "woods",
                    "alternatives": [
                        {
                            "value": "woods",
                            "confidence": 0.8
                        },
                        {
                            "value": "what's",
                            "confidence": 0.2
                        }
                    ]
                },
                ...
            ]
        }
    }
]

7. Generating subtitles

When audio processing is complete we are able to generate subtitle from the collected result.

GET /cox/audio/{{requestId}}/subtitle/{{format}}

Example shows request for generating subtitle for requestId and SRT format. Two subtitle formats are supported: SRT and STL. When generating with GET request default subtitle generation parameters are used. More on default parameters you can find in Speech To Text section.

curl -X GET \
  https://api.aiconix.cloud/v1/cox/audio/3d4b3370-041d-4b7c-bf58-94fc7262a036/subtitle/srt \
  -H 'Content-Type: application/json'

POST /cox/audio/{{requestId}}/subtitle/{{format}}

Example shows request for generating subtitle for requestId and SRT format. Two subtitle formats are supported: SRT and STL. More on configuration you can find in Speech To Text section

curl -X POST \
  https://api.aiconix.cloud/v1/cox/audio/3d4b3370-041d-4b7c-bf58-94fc7262a036/subtitle/srt \
  -H 'Content-Type: application/json' \
  -d '{
    "maxNumberOfChars": "40",
    "maxNumberOfLines": "4",
    "minCaptionDuration": "2"
  }'

Guide: Speech To Text

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/audio/processUploadedFile \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey" : "363080f0-f5fa-4eb0-a024-4314a825b183",
    "fileId" : "5c58982a9fbf77471c924819",
    "fileName" : "testAudioFile.wav"
}'

Return

4768f101-b4c6-40fc-95a5-7ab37dc9eaa1

POST /cox/audio/processUploadedFile

Description

Converts speech to text.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
fileID string The id from the upload call, so we know which file we need to process.
fileName string You need to give your file a name, such that we process it further.

Response

Parameter Type Description
requestID string Request ID to poll results of provider.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/audio/34c4166e-c960-433a-b0bc-3b85bdfc55e3

Return

[
    {
            "providers": [
                "Google"
            ],
            "requestId": "b6023d84-b86e-4dce-b149-01201da8ada1",
            "mediaType": "Audio",
            "operationMode": "RawOverallResult",
            "processingFinished": true,
            "audioTranscriptionResult": {
                "status": "Success",
                "transcript": "whose woods these are I think I know his house is in the village though",
                "confidence": 0.9848530888557434,
                "words": [
                    {
                        "value": "whose",
                        "startTime": 100,
                        "endTime": 600
                    },
                    {
                        "value": "woods",
                        "startTime": 600,
                        "endTime": 700
                    },

                    ...

                    {
                        "value": "though",
                        "startTime": 3300,
                        "endTime": 3800
                    }
                ]
            }
        }
]

GET /cox/audio

Description

Requests the transcription content from the audio file.

Request

Parameter Type Description
requestID (required) string Identifier from the post request.

Response

Parameter Type Description
providers string[] List of providers.
requestID string Corresponding request ID.
mediaType string Type of media sent to the provider: audio.
operationMode string Operation mode selected in the COX API configuration. Can be "RawOverallResult", "BudgetResult", "BestResults" or "MatchingResult".
processingFinished bool Flag if processing is finished true or false. If false then try to poll the result until it returns true.

Audio Transcription Result

Parameter Type Description
status string Polling, waiting for results from provider. More information to Status Codes is provided here.
featureError string "Result not ready" if status is polling.
transcript string Converted text from the audio file
confidence number($double) Overall percentage of correctly transcribed text [0-1].
value string Recognized word.
confidence number($double) Percentage of words [0-1].
startTime integer Start time of the word in milliseconds.
endTime integer End time of the word in milliseconds.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

GET /cox/audio/{{requestId}}/subtitle/{{format}}

Description

Requests subtitle generation for provided requestId and format. Default subtitle generation parameters are used: Maximum Characters Per Line is 30, Maximum Number Of Lines is 2 and Minimum Caption Duration is 1.5 seconds.

Request

Parameter Type Description
requestID (required) string Identifier from the post request.
format (required) string Subtitle format type. Currently supported formats are srt and stl

Response

Response is in form of a plain formatted text.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

POST /cox/audio/{{requestId}}/subtitle/{{format}}

Description

Requests subtitle generation for provided requestId, format and generation parameters

Request

Parameter Type Description
requestID (required) string Identifier from the post request.
format (required) string Subtitle format type. Currently supported formats are srt and stl

Body

Parameter Type Description
maxCharactersPerLine integer Maximum number of character that can be displayed within single line in caption. If not specified default value of 30 chars is used.
maxNumberOfLines integer Maximum number of lines that can be present in single caption. If not specified default value of 2 lines is used.
minCaptionDuration number Minimum duration that single standalone caption may have. If not specified default value of 1.5 seconds is used.

All parameter values in body have upper limits.

- maxCharactersPerLine should be lower than 150 characters.

- maxNumberOfLines should be lower than 10.

- minCaptionDuration should be lower than 10 seconds.

Response

Response is in form of a plain formatted text.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Guide: Speech To Text With Matching Mode

This guide will step you through the usage of our api in order to get time codes for your existing transcript.

1. Authenticate against the Upload Service

In order to communicate with the upload service we need to request a bearer token.

curl -X POST \
  https://api.aiconix.cloud/v1/auth \
  -H 'Content-Type: application/json' \
  -d '{
    "email":"email.address@provider.com",
    "password":"password"
}'

If successfully authenticated against our system you will receive in the header a bearer token , which will be used for further communication with the server.

Authorization -> Bearer laksdfj823jhlkfasdiJjYkBhaWNvbml4LmRlIiwiUk9MRVMivcml0eSI6

2. Upload an audio file

Now we want to upload a .wav file to the server. We do this by the following command.

curl -X POST \
  https://api.aiconix.cloud/v1/file/audio \
  -H 'Authorization: Bearer BEARER-TOKEN' \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'file=@C:\Users\cb\Desktop\api-data-samples\audio\h_orig.wav'

When successfully uploaded we receive a fileID from the server which is linked to our account.

5c58982a9fbf77471c924819

3. Upload transcript file

Now we want to upload a .txt file that contain transcript of uploaded audio file. We do this by the following command.

curl -X POST \
  https://api.aiconix.cloud/v1/file/transcript \
  -H 'Authorization: Bearer BEARER-TOKEN' \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F mediaFileId=5c58982a9fbf77471c924819 \
  -F 'file=@C:\Users\cb\Desktop\api-data-samples\audio\h_orig_transcript.txt'

After sending the request call we receive a HTTP 200 OK response.

4. Generate an API key

Before we can process a file we need to configure an api key. Please go to config.aiconix.cloud and configure yourself a key for speech to text conversion. Copy the key from the page since we need it in the next step.

Slate guide audio manual transcript

5. Initiate processing of file

Now we can initiate the processing of our uploaded file. We simply need to pass the currently configured apiKey, received fileID and a certain fileName with the matching audio file format.

curl -X POST \
  https://api.aiconix.cloud/v1/cox/audio/processUploadedFile \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey" : "363080f0-f5fa-4eb0-a024-4314a825b183",
    "fileId" : "5c58982a9fbf77471c924819",
    "fileName" : "testAudioFile.wav"
}'

After sending the request call we receive a process id.

4768f101-b4c6-40fc-95a5-7ab37dc9eaa1

6. Poll for request

With the before received processID we can poll for results.

curl -X GET \
  https://api.aiconix.cloud/v1/cox/audio/34c4166e-c960-433a-b0bc-3b85bdfc55e3

We need to poll since different providers process the files differently. You can see in the return field "processingFinished", which provider return already a result and which did not yet.

{
        "providers": [
            "aiconix"
        ],
        "requestId": "083739c6-47d0-4b15-a5ee-9892b9d96e81",
        "mediaType": "Audio",
        "operationMode": "MatchingResult",
        "processingFinished": false,
        "audioTranscriptionResult": {
            "status": "Polling",
            "featureError": "Result not ready..."
        }
}

7. Receive result

The processing is complete if all providers return true in their respective processingFinished flags.

[
    {
        "providers": [
            "aiconix"
        ],
        "requestId": "4768f101-b4c6-40fc-95a5-7ab37dc9eaa1",
        "mediaType": "Audio",
        "operationMode": "MatchingResult",
        "processingFinished": true,
        "audioTranscriptionResult": {
            "status": "Success",
            "transcript": "Who's what's these are I think I know his houses - in the village though.",
            "confidence": 0.7122456186865265,
            "words": [
                {
                    "value": "Whose",
                    "alternatives": [
                        {
                            "value": "Whose",
                            "confidence": 0.8
                        },
                        {
                            "value": "Who's",
                            "confidence": 0.2
                        }
                    ]
                },
                {
                    "value": "woods",
                    "alternatives": [
                        {
                            "value": "woods",
                            "confidence": 0.8
                        },
                        {
                            "value": "what's",
                            "confidence": 0.2
                        }
                    ]
                },
                ...
            ]
        }
    }
]

8. Get subtitle

Once results are ready, we can download subtitle file (transcript with time codes) from our service

curl -X POST \
  https://api.aiconix.cloud/v1/cox/audio/34c4166e-c960-433a-b0bc-3b85bdfc55e3/subtitle/srt
  -H 'Content-Type: application/json' \
  -d '{
    "maxCharactersPerLine" : "30",
    "maxNumberOfLines" : "2",
    "minCaptionDuration" : "1.5"
  }'

Body

Parameter Type Description
maxCharactersPerLine integer Maximum number of character that can be displayed within single line in caption. If not specified default value of 30 chars is used.
maxNumberOfLines integer Maximum number of lines that can be present in single caption. If not specified default value of 2 lines is used.
minCaptionDuration number Minimum duration that single standalone caption may have. If not specified default value of 1.5 seconds is used.

All parameter values in body have upper limits.

- maxCharactersPerLine should be lower than 150 characters.

- maxNumberOfLines should be lower than 10.

- minCaptionDuration should be lower than 10 seconds.

We will receive plain text in Srt format

1
00:00:00,300 --> 00:00:02,375
Who's what's these are I think

2
00:00:02,375 --> 00:00:03,870
I know his houses - in the village though.

Processing from URL

Our API is also supporting audio processing from URL. In this API call, instead of sending whole file, user can send only URL to file that needs to be processed.

1. Generate an API key

Before we can process a file we need to configure an api key. Please go to config.aiconix.cloud and configure yourself a key for speech to text conversion. Copy the key from the page since we need it in the next step.

Slate guide audio

2. Initiate processing of file from URL

Instead of sending file, url to the file can be provided and aingine will download file and start processing.

curl -X POST \
  https://api.aiconix.cloud/v1/cox/audio/processFromUrl \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'url=https://audio.aiconix.cloud/audios/3861961.mp3' \
  -F apiKey=a40c3fc2-585f-4bd0-90be-a95db46be026

After sending the request call we receive a process id.

4768f101-b4c6-40fc-95a5-7ab37dc9eaa1

3. Poll for request

With the before received processID we can poll for results.

curl -X GET \
  https://api.aiconix.cloud/v1/cox/audio/34c4166e-c960-433a-b0bc-3b85bdfc55e3

We need to poll since different providers process the files differently. You can see in the return field "processingFinished", which provider return already a result and which did not yet.

{
        "providers": [
            "aiconix"
        ],
        "requestId": "4768f101-b4c6-40fc-95a5-7ab37dc9eaa1",
        "mediaType": "Audio",
        "operationMode": "BestResults",
        "processingFinished": false,
        "audioTranscriptionResult": {
            "status": "Polling",
            "featureError": "Result not ready..."
        }
}

4. Receive result

The processing is complete if all providers return true in their respective processingFinished flags.

[
    {
        "providers": [
            "aiconix"
        ],
        "requestId": "4768f101-b4c6-40fc-95a5-7ab37dc9eaa1",
        "mediaType": "Audio",
        "operationMode": "BestResults",
        "processingFinished": true,
        "audioTranscriptionResult": {
            "status": "Success",
            "transcript": "Who's what's these are I think I know his houses - in the village though.",
            "confidence": 0.7122456186865265,
            "words": [
                {
                    "value": "Whose",
                    "alternatives": [
                        {
                            "value": "Whose",
                            "confidence": 0.8
                        },
                        {
                            "value": "Who's",
                            "confidence": 0.2
                        }
                    ]
                },
                {
                    "value": "woods",
                    "alternatives": [
                        {
                            "value": "woods",
                            "confidence": 0.8
                        },
                        {
                            "value": "what's",
                            "confidence": 0.2
                        }
                    ]
                },
                ...
            ]
        }
    }
]

5. Get subtitle

Once results are ready, we can download subtitle file (transcript with time codes) from our service

curl -X POST \
  https://api.aiconix.cloud/v1/cox/audio/4768f101-b4c6-40fc-95a5-7ab37dc9eaa1/subtitle/srt
  -H 'Content-Type: application/json' \
  -d '{
    "maxCharactersPerLine" : "30",
    "maxNumberOfLines" : "2",
    "minCaptionDuration" : "1.5"
  }'

Body

Parameter Type Description
maxCharactersPerLine integer Maximum number of character that can be displayed within single line in caption. If not specified default value of 30 chars is used.
maxNumberOfLines integer Maximum number of lines that can be present in single caption. If not specified default value of 2 lines is used.
minCaptionDuration number Minimum duration that single standalone caption may have. If not specified default value of 1.5 seconds is used.

All parameter values in body have upper limits.

- maxCharactersPerLine should be lower than 150 characters.

- maxNumberOfLines should be lower than 10.

- minCaptionDuration should be lower than 10 seconds.

We will receive plain text in Srt format

1
00:00:00,300 --> 00:00:02,375
Who's what's these are I think

2
00:00:02,375 --> 00:00:03,870
I know his houses - in the village though.

Audio Limitations

Following limitations apply for Aingine Audio API

Limitations for Audio media type

Description Values
Supported extensions mp3, m4a, wav, flac, aiff, au, ogg, aac
Maximum file size 2048 MB

Limitations for Audio Subtitle generation

POST /cox/audio/{{requestId}}/subtitle/{{format}}

Description Values
Maximum Characters Per Line < 150 characters
Maximum Number Of Lines < 10
Minimum Caption Duration < 10 seconds

Video

Guide

This guide will step you through the usage of our api in order to perform a face detection on a video file.

1. Authenticate against the Upload Service

In order to communicate with the upload service we need to request a bearer token.

curl -X POST \
  https://api.aiconix.cloud/v1/auth \
  -H 'Content-Type: application/json' \
  -d '{
    "email":"email.address@provider.com",
    "password":"password"
}'

If successfully authenticated against our system you will receive in the header a bearer token , which will be used for further communication with the server.

Authorization -> Bearer laksdfj823jhlkfasdiJjYkBhaWNvbml4LmRlIiwiUk9MRVMivcml0eSI6

2. Upload a video file

Now we want to upload a .mp4 file to the server. We do this by the following command.

curl -X POST \
  https://api.aiconix.cloud/v1/file/video \
  -H 'Authorization: Bearer BEARER-TOKEN' \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'file=@C:\Users\cb\Desktop\api-data-samples\video\SampleVideo_1280x720_1mb.mp4'

When successfully uploaded we receive a fileID from the server which is linked to our account.

5c58982a9fbf77471c924819

3. Generate an API key

Before we can process a file we need to configure an api key. Please go to config.aiconix.cloud and configure yourself a key for face detection. Copy the key from the page since we need it in the next step.

Slate guide video

4. Initiate processing of file

Now we can initiate the processing of our uploaded file. We simply need to pass the currently configured apiKey, received fileID and a certain fileName with the matching video file format.

curl -X POST \
  https://api.aiconix.cloud/v1/cox/video/processUploadedFile \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey" : "363080f0-f5fa-4eb0-a024-4314a825b183",
    "fileId" : "5c58982a9fbf77471c924819",
    "fileName" : "testMovie.mp4"
}'

After sending the request call we receive a process id.

2c2e190d-bafe-4d94-93b3-b49fa220f771

5. Poll for request

With the before received processID we can poll for results.

curl -X GET \
  https://api.aiconix.cloud/v1/cox/video/2c2e190d-bafe-4d94-93b3-b49fa220f771

We need to poll since different providers process the files differently. You can see in the return field "processingFinished", which provider return already a result and which did not yet.

[
    {
        "providers": [
            "Amazon"
        ],
        "requestId": "2c2e190d-bafe-4d94-93b3-b49fa220f771",
        "mediaType": "Video",
        "operationMode": "RawOverallResult",
        "processingFinished": false,
        "faceDetectionResult": {
            "status": "Polling",
            "featureError": "Result not ready..."
        }
    }
]

6. Receive result

The processing is complete if all providers return true in their respective processingFinished flags.

[
    {
        "providers": [
            "Amazon"
        ],
        "requestId": "2c2e190d-bafe-4d94-93b3-b49fa220f771",
        "mediaType": "Video",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "faceDetectionResult": {
            "status": "Success",
            "detectedFacesWithTimeInterval": [
                {
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.25995659828186035,
                                "y": 0.5190658569335938
                            },
                            {
                                "x": 0.25995659828186035,
                                "y": 0.6302790641784668
                            },
                            {
                                "x": 0.30862823128700256,
                                "y": 0.5190658569335938
                            },
                            {
                                "x": 0.30862823128700256,
                                "y": 0.6302790641784668
                            }
                        ]
                    },
                    "confidence": 0.8913286328315735,
                    "interval": {
                        "startTime": 0,
                        "endTime": 200
                    }
                },
                ...
                {
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.3112625479698181,
                                "y": 0.16698360443115234
                            },
                            {
                                "x": 0.3112625479698181,
                                "y": 0.3856832981109619
                            },
                            {
                                "x": 0.42489778995513916,
                                "y": 0.16698360443115234
                            },
                            {
                                "x": 0.42489778995513916,
                                "y": 0.3856832981109619
                            }
                        ]
                    },
                    "confidence": 0.9784935712814331,
                    "interval": {
                        "startTime": 5200,
                        "endTime": 5400
                    }
                }
            ]
        }
    }
]

Block Detection

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/video/processUploadedFile \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey" : "363080f0-f5fa-4eb0-a024-4314a825b183",
    "fileId" : "5c58982a9fbf77471c924819",
    "fileName" : "testMovie.mp4"
}'

Return

a2040de6-c537-4cec-aa5e-8ce0e3c4dc6d

POST /cox/video/processUploadedFile

Description

Request the API to check for blocks in the video.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
fileID string The ID from the upload call, so we know which file we need to process.
fileName string You need to give your file a name, such that we process it further.

Response

Parameter Type Description
requestID string Request ID to poll results of provider.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/video/3230eccc-91a7-4528-85c5-d363531dc186

Return

[
    {
        "providers": [
            "Microsoft"
        ],
        "requestId": "ac37bf9a-5c36-4317-8802-f82c0055a877",
        "mediaType": "Video",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "blockResult": {
            "status": "Success",
            "blocks": [
                {
                    "startTime": 0,
                    "endTime": 5280
                }
            ]
        }
    }
]

GET /cox/video

Description

Retrieve the block results information.

Request

Parameter Type Description
requestID (required) string Identifier from the post request.

Response

Parameter Type Description
providers string[] List of providers.
requestID string Corresponding request ID.
mediaType string Type of media sent to the provider: video.
operationMode string Operation mode selected in the COX API configuration. Can be only "RawOverallResult" for video.
processingFinished bool Flag if processing is finished True or False.

Block Result

Parameter Type Description
status string Polling, waiting for results from provider. More information to Status Codes is provided here.
featureError string Description of failure during processing.
blocks object[] Block list with time limits.
startTime number($integer) Start time of the block.
endTime number($integer) End time of the block.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Content Moderation

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/video/processUploadedFile \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey" : "363080f0-f5fa-4eb0-a024-4314a825b183",
    "fileId" : "5c58982a9fbf77471c924819",
    "fileName" : "testMovie.mp4"
}'

Return

a2040de6-c537-4cec-aa5e-8ce0e3c4dc6d

POST /cox/video/processUploadedFile

Description

Categorization of explicit content e.g. adult, racy, medical, spoof, violence, etc.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
fileID string The ID from the upload call, so we know which file we need to process.
fileName string You need to give your file a name, such that we process it further.

Response

Parameter Type Description
requestID string Request ID to poll results of provider.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/video/3230eccc-91a7-4528-85c5-d363531dc186

Return

[
    {
        "providers": [
            "Google"
        ],
        "requestId": "4e814fc1-e710-466a-a0ca-f4cd9f346607",
        "mediaType": "Video",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "contentModerationResult": {
            "status": "Success",
            "contentModerations": [
                {
                    "description": "Erwachsener",
                    "confidence": 0.4,
                    "interval": {
                        "startTime": 381,
                        "endTime": 381
                    }
                }
            ],
            "originalContentModerations": [
                {
                    "description": "Adult",
                    "confidence": 0.4,
                    "interval": {
                        "startTime": 381,
                        "endTime": 381
                    }
                }
            ],
            "language": "de-DE"
        }
    }
]

GET /cox/video

Description

Retrieve the analysis of the video content moderation analysis.

Request

Parameter Type Description
requestID (required) string Identifier from the post request.

Response

Parameter Type Description
providers string[] List of providers.
requestID string Corresponding request ID.
mediaType string Type of media sent to the provider: video.
operationMode string Operation mode selected in the COX API configuration. Can be only "RawOverallResult" for video.
processingFinished bool Flag if processing is finished True or False.

Content Moderation Result

Parameter Type Description
status string Polling, waiting for results from provider. More information to Status Codes is provided here.
featureError string Description of failure during processing.
contentModerations object[] List of content information.
originalContentModerations object[] If a translation was selected, this contains the content information in their original language.
description string Content moderation category.
confidence number($double) Confidence of categorization.
interval object Contains startTime and endTime of category.
startTime number($integer) Start time of category.
endTime number($integer) End time of category.
language string ISO language code

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Emotion detection

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/video/processUploadedFile \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey" : "363080f0-f5fa-4eb0-a024-4314a825b183",
    "fileId" : "5c58982a9fbf77471c924819",
    "fileName" : "testMovie.mp4"
}'

Return

b3d1760a-43f7-436b-8242-d0c694a8d631

POST /cox/video/processUploadedFile

Description

Request detection of emotions on emotion polygons at certain time frames.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
fileID string The ID from the upload call, so we know which file we need to process.
fileName string You need to give your file a name, such that we process it further.

Response

Parameter Type Description
requestID string Request ID to poll results of provider.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/video/b3d1760a-43f7-436b-8242-d0c694a8d631

Return

[
    {
        "providers": [
            "Amazon"
        ],
        "requestId": "b3d1760a-43f7-436b-8242-d0c694a8d631",
        "mediaType": "Video",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "emotionResult": {
            "status": "Success",
            "emotions": [
                {
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.26079732179641724,
                                "y": 0.5287638306617737
                            },
                            {
                                "x": 0.26079732179641724,
                                "y": 0.6290326118469238
                            },
                            {
                                "x": 0.308646559715271,
                                "y": 0.5287638306617737
                            },
                            {
                                "x": 0.308646559715271,
                                "y": 0.6290326118469238
                            }
                        ]
                    },
                    "emotionProbabilities": [
                        {
                            "emotion": "Unknown",
                            "confidence": 0.5058100819587708
                        },
                        {
                            "emotion": "Anger",
                            "confidence": 0.4564545452594757
                        },
                        {
                            "emotion": "Happiness",
                            "confidence": 0.4510550796985626
                        },
                        {
                            "emotion": "Calmness",
                            "confidence": 0.4612377882003784
                        },
                        {
                            "emotion": "Surprise",
                            "confidence": 0.4562625586986542
                        },
                        {
                            "emotion": "Disgust",
                            "confidence": 0.45172205567359924
                        },
                        {
                            "emotion": "Sadness",
                            "confidence": 0.4645642936229706
                        },
                        {
                            "emotion": "Confusion",
                            "confidence": 0.45289361476898193
                        }
                    ],
                    "interval": {
                        "startTime": 0,
                        "endTime": 200
                    }
                },
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.3024667203426361,
                                "y": 0.3370908498764038
                            },
                            {
                                "x": 0.3024667203426361,
                                "y": 0.5489340424537659
                            },
                            {
                                "x": 0.3966100811958313,
                                "y": 0.3370908498764038
                            },
                            {
                                "x": 0.3966100811958313,
                                "y": 0.5489340424537659
                            }
                        ]
                    },
                    "emotionProbabilities": [
                        {
                            "emotion": "Unknown",
                            "confidence": 0.0012842010473832488
                        },
                        {
                            "emotion": "Anger",
                            "confidence": 0.0019079253543168306
                        },
                        {
                            "emotion": "Happiness",
                            "confidence": 0.5069429874420166
                        },
                        {
                            "emotion": "Calmness",
                            "confidence": 0.10326645523309708
                        },
                        {
                            "emotion": "Surprise",
                            "confidence": 0.38128557801246643
                        },
                        {
                            "emotion": "Disgust",
                            "confidence": 9.037955314852297E-4
                        },
                        {
                            "emotion": "Sadness",
                            "confidence": 0.0011159814894199371
                        },
                        {
                            "emotion": "Confusion",
                            "confidence": 0.0032930420711636543
                        }
                    ],
                    "interval": {
                        "startTime": 600,
                        "endTime": 800
                    }
                },
            ]
        }
    }
]

GET /cox/video

Description

Retrieve the analysis of the video emotions detection.

Request

Parameter Type Description
requestID (required) string Identifier from the post request.

Response

Parameter Type Description
providers string[] List of providers.
requestID string Corresponding request ID.
mediaType string Type of media sent to the provider: video.
operationMode string Operation mode selected in the COX API configuration. Can be only "RawOverallResult" for video.
processingFinished bool Flag if processing is finished True or False.

Emotion Detection Result

Parameter Type Description
status string Polling, waiting for results from provider. More information to Status Codes is provided here.
featureError string Description of failure during processing.
emotions object[] List of detected emotions.
boundingPoly object[] Contains vertices information.
vertices object[] Contains x and y coordinates of polygon corners.
x number($double) Percentage of horizontal position [0-1].
y number($double) Percentage of vertical position [0-1].
emotionProbabilities object[] List of detected emotions on a face.
emotion string Name of detected emotion.
confidence number($double) Confidence value of emotion detection.
interval object List of start and end time of emotion detection interval.
startTime number($integer) Start time of emotion detection in ms.
endTime number($integer) End time of emotion detection in ms.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Face Detection

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/video/processUploadedFile \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey" : "363080f0-f5fa-4eb0-a024-4314a825b183",
    "fileId" : "5c58982a9fbf77471c924819",
    "fileName" : "testMovie.mp4"
}'

Return

a2040de6-c537-4cec-aa5e-8ce0e3c4dc6d

POST /cox/video/processUploadedFile

Description

Request face detection polygons of a video at certain time frames.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
fileID string The ID from the upload call, so we know which file we need to process.
fileName string You need to give your file a name, such that we process it further.

Response

Parameter Type Description
requestID string Request ID to poll results of provider.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/video/3230eccc-91a7-4528-85c5-d363531dc186

Return

[
    {
        "providers": [
            "Amazon"
        ],
        "requestId": "96078b14-618d-4943-8607-4c0e3e3fd756",
        "mediaType": "Video",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "faceDetectionResult": {
            "status": "Success",
            "detectedFacesWithTimeInterval": [
                {
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.6105769276618958,
                                "y": 0.2916666567325592
                            },
                            {
                                "x": 0.6105769276618958,
                                "y": 0.3589743375778198
                            },
                            {
                                "x": 0.661057710647583,
                                "y": 0.2916666567325592
                            },
                            {
                                "x": 0.661057710647583,
                                "y": 0.3589743375778198
                            }
                        ]
                    },
                    "confidence": 0.8839528560638428,
                    "interval": {
                        "startTime": 8600,
                        "endTime": 8800
                    }
                },
                ...
                {
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.29807692766189575,
                                "y": 0.13461539149284363
                            },
                            {
                                "x": 0.29807692766189575,
                                "y": 0.3782051205635071
                            },
                            {
                                "x": 0.48076924681663513,
                                "y": 0.13461539149284363
                            },
                            {
                                "x": 0.48076924681663513,
                                "y": 0.3782051205635071
                            }
                        ]
                    },
                    "confidence": 0.9995610117912292,
                    "interval": {
                        "startTime": 285680,
                        "endTime": 285880
                    }
                }
            ]
        }
    }
]

GET /cox/video

Description

Retrieve the analysis of the video face detection.

Request

Parameter Type Description
requestID (required) string Identifier from the post request.

Response

Parameter Type Description
providers string[] List of providers.
requestID string Corresponding request ID.
mediaType string Type of media sent to the provider: video.
operationMode string Operation mode selected in the COX API configuration. Can be only "RawOverallResult" for video.
processingFinished bool Flag if processing is finished True or False.

Face Detection Result

Parameter Type Description
status string Polling, waiting for results from provider. More information to Status Codes is provided here.
featureError string Description of failure during processing.
detectedFacesWithTimeInterval object[] List of polygons.
boundingPoly object[] Contains vertices information.
vertices object[] Contains x and y coordinates of polygon corners.
x number($double) Percentage of horizontal position [0-1].
y number($double) Percentage of vertical position [0-1].
confidence number($double) Confidence value of face detection.
interval object List of start and end time of face detection interval.
startTime number($integer) Start time of face detection in ms.
endTime number($integer) End time of face detection in ms.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Face Recognition

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/video/processUploadedFile \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey" : "363080f0-f5fa-4eb0-a024-4314a825b183",
    "fileId" : "5c58982a9fbf77471c924819",
    "fileName" : "testMovie.mp4"
}'

Return

12c30b57-ffe0-46a7-aa9a-1c3643e66748

POST /cox/video/processUploadedFile

Description

Request face recognition of celebrities etc. polygons of a video at certain time frames.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
fileID string The ID from the upload call, so we know which file we need to process.
fileName string You need to give your file a name, such that we process it further.

Response

Parameter Type Description
requestID string Request ID to poll results of provider.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/video/3230eccc-91a7-4528-85c5-d363531dc186

Return


[
    {
        "providers": [
            "Amazon"
        ],
        "requestId": "12c30b57-ffe0-46a7-aa9a-1c3643e66748",
        "mediaType": "Video",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "faceRecognitionResult": {
            "status": "Success",
            "recognizedFaces": [
                {
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.18269231915473938,
                                "y": 0.19230769574642181
                            },
                            {
                                "x": 0.18269231915473938,
                                "y": 0.3493589758872986
                            },
                            {
                                "x": 0.30048078298568726,
                                "y": 0.19230769574642181
                            },
                            {
                                "x": 0.30048078298568726,
                                "y": 0.3493589758872986
                            }
                        ]
                    },
                    "confidence": 0.9998807311058044,
                    "interval": {
                        "startTime": 27440,
                        "endTime": 27640
                    },
                    "name": "Mel McDaniel"
                },
                {
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.18269231915473938,
                                "y": 0.19230769574642181
                            },
                            {
                                "x": 0.18269231915473938,
                                "y": 0.3493589758872986
                            },
                            {
                                "x": 0.30048078298568726,
                                "y": 0.19230769574642181
                            },
                            {
                                "x": 0.30048078298568726,
                                "y": 0.3493589758872986
                            }
                        ]
                    },
                    "confidence": 0.999833345413208,
                    "interval": {
                        "startTime": 27640,
                        "endTime": 27840
                    },
                    "name": "Mel McDaniel"
                },

                ...

                {
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.3197115361690521,
                                "y": 0.16346153616905212
                            },
                            {
                                "x": 0.3197115361690521,
                                "y": 0.442307710647583
                            },
                            {
                                "x": 0.5288461446762085,
                                "y": 0.16346153616905212
                            },
                            {
                                "x": 0.5288461446762085,
                                "y": 0.442307710647583
                            }
                        ]
                    },
                    "confidence": 0.999452531337738,
                    "interval": {
                        "startTime": 283720,
                        "endTime": 283920
                    },
                    "name": "Sanjay Gandhi"
                }
            ]
        }
    }
]

GET /cox/video

Description

Retrieve the analysis of the face detection.

Request

Parameter Type Description
requestID (required) string Identifier from the post request.

Response

Parameter Type Description
providers string[] List of providers.
requestID string Corresponding request ID.
mediaType string Type of media sent to the provider: video.
operationMode string Operation mode selected in the COX API configuration. Can be only "RawOverallResult" for video.
processingFinished bool Flag if processing is finished True or False.

Face Recognition Result

Parameter Type Description
status string Polling, waiting for results from provider. More information to Status Codes is provided here.
featureError string Description of failure during processing.
recognizedFaces object[] List of polygons.
boundingPoly object[] Contains vertices information.
vertices object[] Contains x and y coordinates of polygon corners.
x number($double) Percentage of horizontal position [0-1].
y number($double) Percentage of vertical position [0-1].
confidence number($double) Confidence value of face recognition.
interval object List of start and end time of face recognition interval.
startTime number($integer) Start time of recognized face in ms.
endTime number($integer) End time of recognized face in ms.
name string Name of the the recognized person.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Face Landmarks Detection

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/video/processUploadedFile \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey" : "363080f0-f5fa-4eb0-a024-4314a825b183",
    "fileId" : "5c58982a9fbf77471c924819",
    "fileName" : "testMovie.mp4"
}'

Return

6f8315f2-0449-49e1-bb38-74f302b2d9da

POST /cox/video/processUploadedFile

Description

Request the facial landmarks (eyeLeft, mouthRight, etc...) for each detected face of a video at a certain time frames.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
fileID string The ID from the upload call, so we know which file we need to process.
fileName string You need to give your file a name, such that we process it further.

Response

Parameter Type Description
requestID string Request ID to poll results of provider.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/video/3230eccc-91a7-4528-85c5-d363531dc186

Return

[
    {
        "providers": [
            "Amazon"
        ],
        "requestId": "4c196ea4-9785-4c70-b951-6e960bd9ccd0",
        "mediaType": "Video",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "facialLandmarksResult": {
            "status": "Success",
            "landmarkFaces": [
                {
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.3512571454048157,
                                "y": 0.2641593813896179
                            },
                            {
                                "x": 0.3512571454048157,
                                "y": 0.8086194396018982
                            },
                            {
                                "x": 0.6438658833503723,
                                "y": 0.2641593813896179
                            },
                            {
                                "x": 0.6438658833503723,
                                "y": 0.8086194396018982
                            }
                        ]
                    },
                    "facialLandmarks": [
                        {
                            "landmarkType": "eyeLeft",
                            "position": {
                                "x": 0.45172199606895447,
                                "y": 0.44281771779060364
                            }
                        },
                        {
                            "landmarkType": "eyeRight",
                            "position": {
                                "x": 0.5775090456008911,
                                "y": 0.45549720525741577
                            }
                        },
                        {
                            "landmarkType": "mouthLeft",
                            "position": {
                                "x": 0.4532294273376465,
                                "y": 0.661217987537384
                            }
                        },
                        {
                            "landmarkType": "mouthRight",
                            "position": {
                                "x": 0.558280348777771,
                                "y": 0.6708778738975525
                            }
                        },
                        {
                            "landmarkType": "nose",
                            "position": {
                                "x": 0.5254984498023987,
                                "y": 0.5666207075119019
                            }
                        }
                    ],
                    "interval": {
                        "startTime": 0,
                        "endTime": 200
                    }
                }
            ]
        }
    }
]

GET /cox/video

Description

Retrieve the facial landmarks for each detected face at a certain time frames

Request

Parameter Type Description
requestID (required) string Identifier from the post request.

Response

Parameter Type Description
providers string[] List of providers.
requestID string Corresponding request ID.
mediaType string Type of media sent to the provider: video.
operationMode string Operation mode selected in the COX API configuration. Can be only "RawOverallResult" for video.
processingFinished bool Flag if processing is finished True or False.

Facial Landmarks Result

Parameter Type Description
status string Success when result it ready, polling when provider is still calculating.
featureError string Description of failure during processing.
landmarkFaces object[] landmarksFace list, contains landmarks for all detected faces.
boundingPoly object[] Contains vertices information about detected face.
vertices object[] Contains x and y coordinates of polygon corners.
x (vertex) number($double) Percentage of horizontal position [0-1].
y (vertex) number($double) Percentage of vertical position [0-1].
facialLandmarks object[] Contains data about every detected landmark on a face.
landmarkType string Type of landmark.
position {x,y} Position of landmark on a frame.
x (position) number($double) Percentage of horizontal position [0-1].
y (position) number($double) Percentage of vertical position [0-1].
interval object List of start and end time of face detection interval.
startTime number($integer) Start time of face detection in ms.
endTime number($integer) End time of face detection in ms.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Facial Attributes

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/video/processUploadedFile \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey" : "363080f0-f5fa-4eb0-a024-4314a825b183",
    "fileId" : "5c58982a9fbf77471c924819",
    "fileName" : "testMovie.mp4"
}'

Return

60f7b2c2-886b-4966-a648-9ea1fd3dc15d

POST /cox/video/processUploadedFile

Description

Request facial attributes detection of a video at a certain time frame.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
fileID string The ID from the upload call, so we know which file we need to process.
fileName string You need to give your file a name, such that we process it further.

Response

Parameter Type Description
requestID string Request ID to poll results of provider.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/video/60f7b2c2-886b-4966-a648-9ea1fd3dc15d

Return

[
    {
        "providers": [
            "Amazon"
        ],
        "requestId": "60f7b2c2-886b-4966-a648-9ea1fd3dc15d",
        "mediaType": "Video",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "facialAttributesResult": {
            "status": "Success",
            "facialAttributes": [
                {
                    "ageRange": {
                        "low": 31,
                        "high": 47
                    },
                    "beard": {
                        "hasBeard": false,
                        "confidence": 0.806049644947052
                    },
                    "eyeglasses": {
                        "hasEyeglasses": false,
                        "confidence": 0.9889205694198608
                    },
                    "eyeOpen": {
                        "confidence": 0.9889205694198608,
                        "eyeOpen": true
                    },
                    "gender": {
                        "gender": "Male",
                        "confidence": 0.9673848152160645
                    },
                    "mouthOpen": {
                        "confidence": 0.8969968557357788,
                        "mouthOpen": false
                    },
                    "mustache": {
                        "hasMustache": false,
                        "confidence": 0.9753403663635254
                    },
                    "pose": {
                        "pitch": -0.22082683,
                        "roll": -0.65933394,
                        "yaw": -37.4507
                    },
                    "smile": {
                        "hasSmile": false,
                        "confidence": 0.962833046913147
                    },
                    "sunglasses": {
                        "hasSunglasses": false,
                        "confidence": 0.9953561425209045
                    },
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.23189333081245422,
                                "y": 0.13163235783576965
                            },
                            {
                                "x": 0.23189333081245422,
                                "y": 0.6889311075210571
                            },
                            {
                                "x": 0.5287398099899292,
                                "y": 0.13163235783576965
                            },
                            {
                                "x": 0.5287398099899292,
                                "y": 0.6889311075210571
                            }
                        ]
                    },
                    "interval": {
                        "startTime": 0,
                        "endTime": 200
                    }
                },
                {
                    "ageRange": {
                        "low": 21,
                        "high": 33
                    },
                    "beard": {
                        "hasBeard": false,
                        "confidence": 0.843901515007019
                    },
                    "eyeglasses": {
                        "hasEyeglasses": false,
                        "confidence": 0.984840989112854
                    },
                    "eyeOpen": {
                        "confidence": 0.984840989112854,
                        "eyeOpen": true
                    },
                    "gender": {
                        "gender": "Male",
                        "confidence": 0.9902999401092529
                    },
                    "mouthOpen": {
                        "confidence": 0.9522154331207275,
                        "mouthOpen": false
                    },
                    "mustache": {
                        "hasMustache": false,
                        "confidence": 0.9866421222686768
                    },
                    "pose": {
                        "pitch": 3.777247,
                        "roll": 0.39650023,
                        "yaw": -35.43852
                    },
                    "smile": {
                        "hasSmile": false,
                        "confidence": 0.9904727935791016
                    },
                    "sunglasses": {
                        "hasSunglasses": false,
                        "confidence": 0.9921714663505554
                    },
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.2017023265361786,
                                "y": 0.12400411069393158
                            },
                            {
                                "x": 0.2017023265361786,
                                "y": 0.7007552981376648
                            },
                            {
                                "x": 0.48282021284103394,
                                "y": 0.12400411069393158
                            },
                            {
                                "x": 0.48282021284103394,
                                "y": 0.7007552981376648
                            }
                        ]
                    },
                    "interval": {
                        "startTime": 200,
                        "endTime": 400
                    }
                },

                        ...

                {
                    "ageRange": {
                        "low": 19,
                        "high": 31
                    },
                    "beard": {
                        "hasBeard": false,
                        "confidence": 0.8374744653701782
                    },
                    "eyeglasses": {
                        "hasEyeglasses": false,
                        "confidence": 0.9767414331436157
                    },
                    "eyeOpen": {
                        "confidence": 0.9767414331436157,
                        "eyeOpen": true
                    },
                    "gender": {
                        "gender": "Male",
                        "confidence": 0.996202290058136
                    },
                    "mouthOpen": {
                        "confidence": 0.6604734659194946,
                        "mouthOpen": false
                    },
                    "mustache": {
                        "hasMustache": false,
                        "confidence": 0.9875521063804626
                    },
                    "pose": {
                        "pitch": 10.8571205,
                        "roll": -8.100222,
                        "yaw": -21.425453
                    },
                    "smile": {
                        "hasSmile": false,
                        "confidence": 0.9317398071289062
                    },
                    "sunglasses": {
                        "hasSunglasses": false,
                        "confidence": 0.9864937663078308
                    },
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.24534614384174347,
                                "y": 0.15639285743236542
                            },
                            {
                                "x": 0.24534614384174347,
                                "y": 0.7341758608818054
                            },
                            {
                                "x": 0.5368548631668091,
                                "y": 0.15639285743236542
                            },
                            {
                                "x": 0.5368548631668091,
                                "y": 0.7341758608818054
                            }
                        ]
                    },
                    "interval": {
                        "startTime": 9599,
                        "endTime": 9799
                    }
                }
            ]
        }
    }
]

GET /cox/video

Description

Returns the analysis of the facial attributes detection.

Request

Parameter Type Description
requestID (required) string Identifier from the post request.

Response

Parameter Type Description
providers string[] List of providers.
requestID string Corresponding request ID.
mediaType string Type of media sent to the provider: video.
operationMode string Operation mode selected in the COX API configuration. Can be only "RawOverallResult" for video.
processingFinished bool Flag if processing is finished True or False.

Person Tracking Result

Parameter Type Description
status string Polling, waiting for results from provider. More information to Status Codes is provided here.
featureError string Description of failure during processing.
facialAttributes object[] Facial attributes in an input video.
ageRange object The estimated age range, in years, for the face.
low number($integer) The lowest estimated age.
high number($integer) The highest estimated age.
beard object Indicates whether or not the face has a beard, and the confidence level in the determination.
hasBeard boolean Indicates whether or not the face has a beard.
confidence number($double) Confidence value of beard determination.
eyeglasses object Indicates whether or not the face is wearing eye glasses, and the confidence level in the determination.
hasEyeglasses boolean Indicates whether or not the face is wearing eye glasses.
confidence number($double) Confidence value of eye glasses determination.
eyeOpen object Indicates whether or not the eyes on the face are open, and the confidence level in the determination.
eyeOpen boolean Indicates whether or not the eyes on the face are open.
confidence number($double) Confidence value of eyes open determination.
gender object Gender of the face and the confidence level in the determination.
gender string Gender of the face. Possible values are male or female.
confidence number($double) Confidence value of gender determination.
mouthOpen object Indicates whether or not the mouth on the face is open, and the confidence level in the determination.
mouthOpen boolean Indicates whether or not the mouth on the face is open.
confidence number($double) Confidence value of mouth open determination.
mustache object Indicates whether or not the face has a mustache, and the confidence level in the determination.
hasMustache boolean Indicates whether or not the face has a mustache.
confidence number($double) Confidence value of mustache determination.
pose object Indicates the pose of the face as determined by its pitch, roll, and yaw.
pitch number($double) Value representing the face rotation on the pitch axis.
roll number($double) Value representing the face rotation on the roll axis.
yaw number($double) Value representing the face rotation on the yaw axis.
smile object Indicates whether or not the face is smiling, and the confidence level in the determination.
hasSmile boolean Indicates whether or not the face is smiling.
confidence number($double) Confidence value of smile determination.
sunglasses object Indicates whether or not the face is wearing sunglasses, and the confidence level in the determination..
hasSunglasses boolean Indicates whether or not the face is wearing sunglasses.
confidence number($double) Confidence value of sunglasses determination.
boundingPoly object[] Contains vertices and time offset information.
vertices string Contains x and y coordinates of polygon corners.
x number($double) Percentage of horizontal position [0-1].
y number($double) Percentage of vertical position [0-1].
interval object List of start and end time of facial attributes detection interval.
startTime number($integer) Start time of facial attributes detection in ms.
endTime number($integer) End time of facial attributes detection in ms.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

IAB Categories

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/video/processUploadedFile \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey" : "363080f0-f5fa-4eb0-a024-4314a825b183",
    "fileId" : "5c58982a9fbf77471c924819",
    "fileName" : "testMovie.mp4"
}'

Return

211404ec-cf92-47ef-a428-c03454caa5cf

POST /cox/video/processUploadedFile

Description

Request IAB Categories of a video at a certain time frame.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
fileID string The ID from the upload call, so we know which file we need to process.
fileName string You need to give your file a name, such that we process it further.

Response

Parameter Type Description
requestID string Request ID to poll results of provider.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

HTML Request

GET https://api.aiconix.cloud/v1/cox/video/{requestID}

Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/video/3230eccc-91a7-4528-85c5-d363531dc186

Return


[
{
        "providers": [
            "Valossa"
        ],
        "requestId": "5227f56b-bfed-40d1-afa7-fece1858f1af",
        "mediaType": "Video",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "iabCategoryResult": {
            "status": "Success",
            "iabcategories": [
                {
                    "id": "IAB8",
                    "label": "Food & Drink"
                },
                {
                    "id": "IAB8",
                    "label": "Food & Drink"
                },
                {
                    "id": "IAB18",
                    "label": "Style & Fashion"
                }
            ]
        }
    }
]

GET /cox/video

Description

Retrieve the analysis of the label detection.

Request

Parameter Type Description
requestID (required) string Identifier from the post request.

Response

Parameter Type Description
providers string[] List of providers.
requestID string Corresponding request ID.
mediaType string Type of media sent to the provider: video.
operationMode string Operation mode selected in the COX API configuration. Can be only "RawOverallResult" for video.
processingFinished bool Flag if processing is finished True or False.

IAB Categories Result

Parameter Type Description
status string Polling, waiting for results from provider. More information to Status Codes is provided here.
featureError string Description of failure during processing.
iabcategories object[] IAB categories found in the video.
id string IAB category identification number.
label string Label of the id.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Keyword Detection

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/video/processUploadedFile \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey" : "363080f0-f5fa-4eb0-a024-4314a825b183",
    "fileId" : "5c58982a9fbf77471c924819",
    "fileName" : "testMovie.mp4"
}'

Return

211404ec-cf92-47ef-a428-c03454caa5cf

POST /cox/video/processUploadedFile

Description

Request keyword detection of a video at a certain time frames.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
fileID string The ID from the upload call, so we know which file we need to process.
fileName string You need to give your file a name, such that we process it further.

Response

Parameter Type Description
requestID string Request ID to poll results of provider.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Request shell curl -X GET \ https://api.aiconix.cloud/v1/cox/video/3230eccc-91a7-4528-85c5-d363531dc186

Return

[
    {
        "providers": [
            "Microsoft"
        ],
        "requestId": "3c0c602d-1722-4086-a611-a77310e71d33",
        "mediaType": "Video",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "keywordResult": {
            "status": "Success",
            "keywords": [
                {
                    "keyword": "people",
                    "confidence": 0.8041,
                    "interval": {
                        "startTime": 17464,
                        "endTime": 19011
                    }
                }

                ...

                {
                    "keyword": "shoes",
                    "confidence": 0.6211,
                    "interval": {
                        "startTime": 3989,
                        "endTime": 12573
                    }
                }
            ]
        }
    }
]

GET /cox/video

Description

Retrieve the analysis of the keyword detection.

Request

Parameter Type Description
requestID (required) string Identifier from the post request.

Response

Parameter Type Description
providers string[] List of providers.
requestID string Corresponding request ID.
mediaType string Type of media sent to the provider: video.
operationMode string Operation mode selected in the COX API configuration. Can be only "RawOverallResult" for video.
processingFinished bool Flag if processing is finished True or False.

Keyword Result

Parameter Type Description
status string Polling, waiting for results from provider. More information to Status Codes is provided here.
featureError string Description of failure during processing.
keywords object[] Array of detected keywords with the respective attributes.
keyword string Detected keyword.
category string Detected category.
confidence number($double) Confidence value of keyword detection.
interval object List of start and end time of keyword detection interval.
startTime number($integer) Start time of detected keyword in ms.
endTime number($integer) End time of detected keyword in ms.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Label Detection

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/video/processUploadedFile \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey" : "363080f0-f5fa-4eb0-a024-4314a825b183",
    "fileId" : "5c58982a9fbf77471c924819",
    "fileName" : "testMovie.mp4"
}'

Return

211404ec-cf92-47ef-a428-c03454caa5cf

POST /cox/video/processUploadedFile

Description

Request label detection of a video at a certain time frame.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
fileID string The ID from the upload call, so we know which file we need to process.
fileName string You need to give your file a name, such that we process it further.

Response

Parameter Type Description
requestID string Request ID to poll results of provider.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

HTML Request

GET https://api.aiconix.cloud/v1/cox/video/{requestID}

Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/video/3230eccc-91a7-4528-85c5-d363531dc186

Return

[
    {
        "providers": [
            "Google"
        ],
        "requestId": "d354d0b0-3a54-439d-af08-3095e94af869",
        "mediaType": "Video",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "labelResult": {
            "status": "Success",
            "labels": [
                {
                    "description": "Bereich",
                    "confidence": 0.33042970299720764,
                    "interval": {
                        "startTime": 0,
                        "endTime": 117240
                    }
                }

                ...

                {
                    "description": "Animation",
                    "confidence": 0.6196030378341675,
                    "interval": {
                        "startTime": 0,
                        "endTime": 117240
                    }
                }
            ],
            "originalLabels": [
                {
                    "description": "field",
                    "confidence": 0.33042970299720764,
                    "interval": {
                        "startTime": 0,
                        "endTime": 117240
                    }
                }

                ...

                {
                    "description": "animation",
                    "confidence": 0.6196030378341675,
                    "interval": {
                        "startTime": 0,
                        "endTime": 117240
                    }
                }
            ],
            "language": "de-DE"
        }
    }
]

GET /cox/video

Description

Retrieve the analysis of the label detection.

Request

Parameter Type Description
requestID (required) string Identifier from the post request.

Response

Parameter Type Description
providers string[] List of providers.
requestID string Corresponding request ID.
mediaType string Type of media sent to the provider: video.
operationMode string Operation mode selected in the COX API configuration. Can be only "RawOverallResult" for video.
processingFinished bool Flag if processing is finished True or False.

Label Result

Parameter Type Description
status string Polling, waiting for results from provider. More information to Status Codes is provided here.
featureError string Description of failure during processing.
labels object[] Label content. If a translation was selected, this contains the labels translated into target language.
description string Description of the scene with a label e.g. Text, Word, Keyboard, People, Studio, etc.
confidence number($double) Confidence value of label detection.
interval string List of start and end time of label detection interval.
startTime number($integer) Start time of detected label in ms.
endTime number($integer) End time of detected label in ms.
originalLabels object[] If a translation was selected, this contains the labels in their original language.
categories string[] Category to which found label belong.
ontologyReferences object[] Metadata for a knowledge graph
ontology string Google knowledge graph - uses the relationships between words and concepts to understand the context of a query and to assign specific meaning to user intents.
entityId string Unique identifier of the concept.
language string ISO language code.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Object Tracking

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/video/processUploadedFile \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey" : "363080f0-f5fa-4eb0-a024-4314a825b183",
    "fileId" : "5c58982a9fbf77471c924819",
    "fileName" : "testMovie.mp4"
}'

Return

aa5275d4-1dbf-4a9f-8958-8e6d9cd317ad

POST /cox/video/processUploadedFile

Description

Request object tracking of a video at a certain time frame.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
fileID string The ID from the upload call, so we know which file we need to process.
fileName string You need to give your file a name, such that we process it further.

Response

Parameter Type Description
requestID string Request ID to poll results of provider.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/video/aa5275d4-1dbf-4a9f-8958-8e6d9cd317ad

Return

[
    {
        "providers": [
            "Google"
        ],
        "requestId": "aa5275d4-1dbf-4a9f-8958-8e6d9cd317ad",
        "mediaType": "Video",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "objectTrackingResult": {
            "status": "Success",
            "objectTracking": [
                {
                    "interval": {
                        "startTime": 0,
                        "endTime": 2280
                    },
                    "description": "animal",
                    "confidence": 0.6366145610809326,
                    "boundingPoly": [
                        {
                            "offset": 0,
                            "vertices": [
                                {
                                    "x": 0.046282894909381866,
                                    "y": 0.3160267174243927
                                },
                                {
                                    "x": 0.046282894909381866,
                                    "y": 0.7850000262260437
                                },
                                {
                                    "x": 0.4649999737739563,
                                    "y": 0.3160267174243927
                                },
                                {
                                    "x": 0.4649999737739563,
                                    "y": 0.7850000262260437
                                }
                            ]
                        },
                        {
                            "offset": 120,
                            "vertices": [
                                {
                                    "x": 0.041947368532419205,
                                    "y": 0.35062673687934875
                                },
                                {
                                    "x": 0.041947368532419205,
                                    "y": 0.7600394487380981
                                },
                                {
                                    "x": 0.4197015166282654,
                                    "y": 0.35062673687934875
                                },
                                {
                                    "x": 0.4197015166282654,
                                    "y": 0.7600394487380981
                                }
                            ]
                        },

                            ...

                        {
                            "offset": 2280,
                            "vertices": [
                                {
                                    "x": 0.1579113006591797,
                                    "y": 0.06602209061384201
                                },
                                {
                                    "x": 0.1579113006591797,
                                    "y": 0.8660073280334473
                                },
                                {
                                    "x": 0.49054762721061707,
                                    "y": 0.06602209061384201
                                },
                                {
                                    "x": 0.49054762721061707,
                                    "y": 0.8660073280334473
                                }
                            ]
                        }
                    ]
                },
                {
                    "interval": {
                        "startTime": 1080,
                        "endTime": 1080
                    },
                    "description": "rabbit",
                    "confidence": 0.8757189512252808,
                    "boundingPoly": [
                        {
                            "offset": 1080,
                            "vertices": [
                                {
                                    "x": 0.10805070400238037,
                                    "y": 0.24180194735527039
                                },
                                {
                                    "x": 0.10805070400238037,
                                    "y": 0.8329192399978638
                                },
                                {
                                    "x": 0.5008803606033325,
                                    "y": 0.24180194735527039
                                },
                                {
                                    "x": 0.5008803606033325,
                                    "y": 0.8329192399978638
                                }
                            ]
                        }
                    ]
                },
                {
                    "interval": {
                        "startTime": 2520,
                        "endTime": 4560
                    },
                    "description": "person",
                    "confidence": 0.8316677808761597,
                    "boundingPoly": [
                        {
                            "offset": 2520,
                            "vertices": [
                                {
                                    "x": 0.13244877755641937,
                                    "y": 0.05305774509906769
                                },
                                {
                                    "x": 0.13244877755641937,
                                    "y": 0.855118989944458
                                },
                                {
                                    "x": 0.48203396797180176,
                                    "y": 0.05305774509906769
                                },
                                {
                                    "x": 0.48203396797180176,
                                    "y": 0.855118989944458
                                }
                            ]
                        },

                            ...

                        {
                            "offset": 4560,
                            "vertices": [
                                {
                                    "x": 0.21593213081359863,
                                    "y": 0.10688754916191101
                                },
                                {
                                    "x": 0.21593213081359863,
                                    "y": 0.9096851348876953
                                },
                                {
                                    "x": 0.49566197395324707,
                                    "y": 0.10688754916191101
                                },
                                {
                                    "x": 0.49566197395324707,
                                    "y": 0.9096851348876953
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    }
]

GET /cox/video

Description

Retrieve the analysis of the object tracking provider.

Request

Parameter Type Description
requestID (required) string Identifier from the post request.

Response

Parameter Type Description
providers string[] List of providers.
requestID string Corresponding request ID.
mediaType string Type of media sent to the provider: video.
operationMode string Operation mode selected in the COX API configuration. Can be only "RawOverallResult" for video.
processingFinished bool Flag if processing is finished True or False.

Person Tracking Result

Parameter Type Description
status string Polling, waiting for results from provider. More information to Status Codes is provided here.
featureError string Description of failure during processing.
objectTracking object[] Objects detected in an input video.
interval object Time interval when objects are detected.
startTime number($integer) Start time of object tracking in ms.
endTime number($integer) End time of object tracking in ms.
description string Description of the scene with a object e.g. Text, Animal, Rabbit, Person, Building, etc.
confidence number($double) Confidence value of object tracking.
boundingPoly object[] Contains vertices and time offset information.
offset number($integer) Timestamp when object is detected.
vertices object[] Contains x and y coordinates of polygon corners.
x number($double) Percentage of horizontal position [0-1].
y number($double) Percentage of vertical position [0-1].

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Optical Character Recognition

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/video/processUploadedFile \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey" : "363080f0-f5fa-4eb0-a024-4314a825b183",
    "fileId" : "5c58982a9fbf77471c924819",
    "fileName" : "testMovie.mp4"
}'

Return

ba0ac7b4-2366-4f93-be0a-0cf0fdd74e99

POST /cox/video/processUploadedFile

Description

Request label Optical Character Recognition of a video at a certain time frame.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
fileID string The ID from the upload call, so we know which file we need to process.
fileName string You need to give your file a name, such that we process it further.

Response

Parameter Type Description
requestID string Request ID to poll results of provider.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/video/3230eccc-91a7-4528-85c5-d363531dc186

Return

[
    {
        "providers": [
            "Microsoft"
        ],
        "requestId": "ba0ac7b4-2366-4f93-be0a-0cf0fdd74e99",
        "mediaType": "Video",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "ocrResult": {
            "status": "Success",
            "ocrs": [
                {
                    "text": "This is a real scene",
                    "confidence": 0.8158,
                    "interval": {
                        "startTime": 480,
                        "endTime": 640
                    }
                },
                {
                    "text": "from a netherlandish",
                    "confidence": 0.7039,
                    "interval": {
                        "startTime": 480,
                        "endTime": 640
                    }
                },

                ...

                {
                    "text": "now at a radio",
                    "confidence": 0.5648,
                    "interval": {
                        "startTime": 288480,
                        "endTime": 289120
                    }
                }
            ]
        }
    }
]

GET /cox/video

Description

Retrieve the analysis of the Optical Character Recognition.

Request

Parameter Type Description
requestID (required) string Identifier from the post request.

Response

Parameter Type Description
providers string[] List of providers.
requestID string Corresponding request ID.
mediaType string Type of media sent to the provider: video.
operationMode string Operation mode selected in the COX API configuration. Can be only "RawOverallResult" for video.
processingFinished bool Flag if processing is finished True or False.

OCR Result

Parameter Type Description
status string Polling, waiting for results from provider. More information to Status Codes is provided here.
featureError string Description of failure during processing.
ocrs object[] OCR content.
text string Recognized characters in this time frame.
confidence number($double) Confidence value of OCR.
interval object List of start and end time of OCR interval.
startTime number($integer) Start time of single OCR in ms.
endTime number($integer) End time of single OCR in ms.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Person Tracking

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/video/processUploadedFile \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey" : "363080f0-f5fa-4eb0-a024-4314a825b183",
    "fileId" : "5c58982a9fbf77471c924819",
    "fileName" : "testMovie.mp4"
}'

Return

6f8315f2-0449-49e1-bb38-74f302b2d9da

POST /cox/video/processUploadedFile

Description

Request person tracking of a video at a certain time frame.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
fileID string The ID from the upload call, so we know which file we need to process.
fileName string You need to give your file a name, such that we process it further.

Response

Parameter Type Description
requestID string Request ID to poll results of provider.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/video/3230eccc-91a7-4528-85c5-d363531dc186

Return

[
    {
        "providers": [
            "Amazon"
        ],
        "requestId": "6f8315f2-0449-49e1-bb38-74f302b2d9da",
        "mediaType": "Video",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "personTrackingResult": {
            "status": "Success",
            "personTracking": [
                {
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.32499998807907104,
                                "y": 0.5791666507720947
                            },
                            {
                                "x": 0.32499998807907104,
                                "y": 0.9458333253860474
                            },
                            {
                                "x": 0.5874999761581421,
                                "y": 0.5791666507720947
                            },
                            {
                                "x": 0.5874999761581421,
                                "y": 0.9458333253860474
                            }
                        ]
                    },
                    "interval": {
                        "startTime": 2360,
                        "endTime": 2560
                    },
                    "id": 0
                },

                ...

                {
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.39375001192092896,
                                "y": 0.12916666269302368
                            },
                            {
                                "x": 0.39375001192092896,
                                "y": 0.46666666865348816
                            },
                            {
                                "x": 0.48125001788139343,
                                "y": 0.12916666269302368
                            },
                            {
                                "x": 0.48125001788139343,
                                "y": 0.46666666865348816
                            }
                        ]
                    },
                    "interval": {
                        "startTime": 8120,
                        "endTime": 8320
                    },
                    "id": 1
                },

                    ...
                ,
                {
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.11249999701976776,
                                "y": 0.02083333395421505
                            },
                            {
                                "x": 0.11249999701976776,
                                "y": 0.9458333253860474
                            },
                            {
                                "x": 0.793749988079071,
                                "y": 0.02083333395421505
                            },
                            {
                                "x": 0.793749988079071,
                                "y": 0.9458333253860474
                            }
                        ]
                    },
                    "interval": {
                        "startTime": 285840,
                        "endTime": 286040
                    },
                    "id": 117
                }
            ]
        }
    }
]

GET /cox/video

Description

Retrieve the analysis of the person tracking provider.

Request

Parameter Type Description
requestID (required) string Identifier from the post request.

Response

Parameter Type Description
providers string[] List of providers.
requestID string Corresponding request ID.
mediaType string Type of media sent to the provider: video.
operationMode string Operation mode selected in the COX API configuration. Can be only "RawOverallResult" for video.
processingFinished bool Flag if processing is finished True or False.

Person Tracking Result

Parameter Type Description
status string Polling, waiting for results from provider. More information to Status Codes is provided here.
featureError string Description of failure during processing.
personTracking object[] Person Tracking content.
boundingPoly object[] Contains vertices information.
vertices object[] Contains x and y coordinates of polygon corners.
x number($double) Percentage of horizontal position [0-1].
y number($double) Percentage of vertical position [0-1].
interval object List of start and end time of person tracking interval.
startTime number($integer) Start time of tracked person in ms.
endTime number($integer) End time of tracked person in ms.
id number($integer) Incremental number of distinct persons detected in the video.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Shot Detection

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/video/processUploadedFile \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey" : "363080f0-f5fa-4eb0-a024-4314a825b183",
    "fileId" : "5c58982a9fbf77471c924819",
    "fileName" : "testMovie.mp4"
}'

Return

6f8315f2-0449-49e1-bb38-74f302b2d9da

POST /cox/video/processUploadedFile

Description

Request the timestamps where a shot change has been detected in the video.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
fileID string The ID from the upload call, so we know which file we need to process.
fileName string You need to give your file a name, such that we process it further.

Response

Parameter Type Description
requestID string Request ID to poll results of provider.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/video/3230eccc-91a7-4528-85c5-d363531dc186

Return

[
    {
        "providers": [
            "Microsoft"
        ],
        "requestId": "c08775c7-f95d-47cf-a52c-d7414d2199c6",
        "mediaType": "Video",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "shotResult": {
            "status": "Success",
            "shots": [
                {
                    "startTime": 0,
                    "endTime": 2400
                },

                ...


                {
                    "startTime": 251440,
                    "endTime": 271200
                },
                {
                    "startTime": 271200,
                    "endTime": 291200
                }
            ]
        }
    }
]

GET /cox/video

Description

Retrieve the shot changes with time stamps.

Request

Parameter Type Description
requestID (required) string Identifier from the post request.

Response

Parameter Type Description
providers string[] List of providers.
requestID string Corresponding request ID.
mediaType string Type of media sent to the provider: video.
operationMode string Operation mode selected in the COX API configuration. Can be only "RawOverallResult" for video.
processingFinished bool Flag if processing is finished True or False.

Shot Result

Parameter Type Description
status string Success when result it ready, polling when provider is still calculating.
featureError string Description of failure during processing.
shots object[] Shot list.
startTime number($integer) Start time of shot in ms.
endTime number($integer) End time of shot in ms.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Speech To Text

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/video/processUploadedFile \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey" : "363080f0-f5fa-4eb0-a024-4314a825b183",
    "fileId" : "5c58982a9fbf77471c924819",
    "fileName" : "testMovie.mp4"
}'

Return

6f8315f2-0449-49e1-bb38-74f302b2d9da

POST /cox/video/processUploadedFile

Description

Request the text of the video from the audio track.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
fileID string The ID from the upload call, so we know which file we need to process.
fileName string You need to give your file a name, such that we process it further.

Response

Parameter Type Description
requestID string Request ID to poll results of provider.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/video/3230eccc-91a7-4528-85c5-d363531dc186

Return

[
    {
        "providers": [
            "Microsoft"
        ],
        "requestId": "59ac5beb-9603-4ee1-9c03-e1c65572c1ce",
        "mediaType": "Video",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "videoTranscriptionResult": {
            "status": "Success",
            "transcripts": [
                {
                    "confidence": 0.6177,
                    "transcript": "Molecular sucked into the doctors Beijing, Virginia Open and see how recommend that that's leftover from first through your system.",
                    "interval": {
                        "startTime": 7550,
                        "endTime": 23100
                    }
                },
                {
                    "confidence": 0.604,
                    "transcript": "Boomerang and actually a bit over native Linda's birthday, Oh my God, that exfil they help anything in the back.",
                    "interval": {
                        "startTime": 23110,
                        "endTime": 37460
                    }
                },

                ...

                {
                    "confidence": 0.7381,
                    "transcript": "Yup hello hello.",
                    "interval": {
                        "startTime": 87300,
                        "endTime": 101550
                    }
                },
                {
                    "confidence": 0.7367,
                    "transcript": "Cancel the listing of our would be willing to accept anything that will make you poop.",
                    "interval": {
                        "startTime": 101860,
                        "endTime": 132970
                    }
                },
                {
                    "confidence": 0.567,
                    "transcript": "Melissa Lee effect 3.",
                    "interval": {
                        "startTime": 132980,
                        "endTime": 135460
                    }
                },
                {
                    "confidence": 0.6473,
                    "transcript": "Good times near it didn't think it took that Server Delta.",
                    "interval": {
                        "startTime": 135820,
                        "endTime": 140890
                    }
                },

                ...

                {
                    "confidence": 0.5395,
                    "transcript": "DJ going on in beneficial will only run over to kill problem. He's really cool graphic overcome all about their breath.",
                    "interval": {
                        "startTime": 270480,
                        "endTime": 282390
                    }
                }
            ]
        }
    }
]

GET /cox/video

Description

Retrieve the text of the video from the audio track.

Request

Parameter Type Description
requestID (required) string Identifier from the post request.

Response

Parameter Type Description
providers string[] List of providers.
requestID string Corresponding request ID.
mediaType string Type of media sent to the provider: video.
operationMode string Operation mode selected in the COX API configuration. Can be only "RawOverallResult" for video.
processingFinished bool Flag if processing is finished True or False.

Video Transcription Result

Parameter Type Description
status string Polling, waiting for results from provider. More information to Status Codes is provided here.
featureError string Description of failure during processing.
transcripts object[] Transcript content tag.
confidence number($double) Confidence value of face recognition.
transcript string Transcribed text during given time interval.
interval object List of start and end time of face recognition interval.
startTime number($integer) Start time of face recognition in ms.
endTime number($integer) End time of face recognition in ms.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Processing from URL

Our API is also supporting video processing from URL. In this API call, instead of sending whole file, user can send only URL to file that needs to be processed.

1. Generate an API key

Before we can process a file we need to configure an api key. Please go to config.aiconix.cloud and configure yourself a key for face detection. Copy the key from the page since we need it in the next step.

Slate guide video

2. Initiate processing of file

Instead of sending file, url to the file can be provided and aingine will download file and start processing.

curl -X POST \
  https://api.aiconix.cloud/v1/cox/video/processFromUrl \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'url=https://video.aiconix.cloud/videos/357846.mp4' \
  -F apiKey=a40c3fc2-585f-4bd0-90be-a95db46be027

After sending the request call we receive a process id.

2c2e190d-bafe-4d94-93b3-b49fa220f771

3. Poll for request

With the before received processID we can poll for results.

curl -X GET \
  https://api.aiconix.cloud/v1/cox/video/2c2e190d-bafe-4d94-93b3-b49fa220f771

We need to poll since different providers process the files differently. You can see in the return field "processingFinished", which provider return already a result and which did not yet.

[
    {
        "providers": [
            "Amazon"
        ],
        "requestId": "2c2e190d-bafe-4d94-93b3-b49fa220f771",
        "mediaType": "Video",
        "operationMode": "RawOverallResult",
        "processingFinished": false,
        "faceDetectionResult": {
            "status": "Polling",
            "featureError": "Result not ready..."
        }
    }
]

4. Receive result

The processing is complete if all providers return true in their respective processingFinished flags.

[
    {
        "providers": [
            "Amazon"
        ],
        "requestId": "2c2e190d-bafe-4d94-93b3-b49fa220f771",
        "mediaType": "Video",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "faceDetectionResult": {
            "status": "Success",
            "detectedFacesWithTimeInterval": [
                {
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.25995659828186035,
                                "y": 0.5190658569335938
                            },
                            {
                                "x": 0.25995659828186035,
                                "y": 0.6302790641784668
                            },
                            {
                                "x": 0.30862823128700256,
                                "y": 0.5190658569335938
                            },
                            {
                                "x": 0.30862823128700256,
                                "y": 0.6302790641784668
                            }
                        ]
                    },
                    "confidence": 0.8913286328315735,
                    "interval": {
                        "startTime": 0,
                        "endTime": 200
                    }
                },
                ...
                {
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.3112625479698181,
                                "y": 0.16698360443115234
                            },
                            {
                                "x": 0.3112625479698181,
                                "y": 0.3856832981109619
                            },
                            {
                                "x": 0.42489778995513916,
                                "y": 0.16698360443115234
                            },
                            {
                                "x": 0.42489778995513916,
                                "y": 0.3856832981109619
                            }
                        ]
                    },
                    "confidence": 0.9784935712814331,
                    "interval": {
                        "startTime": 5200,
                        "endTime": 5400
                    }
                }
            ]
        }
    }
]

Limitations

Following limitations apply for Aingine Video API

Limitations for Video media type

Description Values
Supported extensions mp4, mov, webm
Maximum file size 2048 MB

Image

Guide

This guide will step you through the usage of our api in order to perform a face detection on an image.

1. Generate an API key

Before we can process a file we need to configure an api key. Please go to config.aiconix.cloud and configure yourself a key for an image media type. Copy the key from the page since we need it in the next step.

Slate guide image

2. Initiate processing of file

Now we can initiate the processing of a file. We simply need to pass the currently configured apiKey and an image file.

curl -X POST \
  https://api.aiconix.cloud/v1/cox/image/processUploadedFileAsync \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'file=@C:\Users\cb\Desktop\api-data-samples\image\President_Barack_Obama.jpg' \
  -F apiKey=a40c3fc2-585f-4bd0-90be-a95db46be026

3. Receive request id

After sending the request we receive the id of the request created for current processing as a plain text response.

e6162496-58c0-4d6d-a5d0-725b83039ec0

4. Poll for result

With the before received processID we can poll for results.

curl -X GET \
  https://api.aiconix.cloud/v1/cox/image/e6162496-58c0-4d6d-a5d0-725b83039ec0

We need to poll since different providers process the files differently. You can see in the return field "processingFinished", which provider return already a result and which did not yet.

{
        "providers": [
            "Google"
        ],
        "requestId": "083739c6-47d0-4b15-a5ee-9892b9d96e81",
        "mediaType": "Image",
        "operationMode": "RawOverallResult",
        "processingFinished": false,
        "faceDetectionResult": {
            "status": "Initiated",
            "featureError": "Result not ready..."
        }
}

5. Receive result

The processing is complete if all providers return true in their respective processingFinished flags.

[
    {
        "providers": [
            "Google"
        ],
        "requestId": "d5a8cdec-4a65-416a-a16c-5360e58312c9",
        "mediaType": "Image",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "faceDetectionResult": {
            "status": "Success",
            "detectedFaces": [
                {
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.3885209858417511,
                                "y": 0.09271523356437683
                            },
                            {
                                "x": 0.3885209858417511,
                                "y": 0.30960264801979065
                            },
                            {
                                "x": 0.6357616186141968,
                                "y": 0.09271523356437683
                            },
                            {
                                "x": 0.6357616186141968,
                                "y": 0.30960264801979065
                            }
                        ]
                    },
                    "confidence": 0.7861414551734924
                }
            ]
        }
    },
    ...
]

Guide: Aiconix Faice

This guide will step you through the usage of our api in order to perform a face identification and face recognition on an image.

1. Generate an API key

Before we can process a file we need to configure an api key. Please go to config.aiconix.cloud and configure yourself a key for Faice Identification and Face Recognition. Copy the key from the page since we need it in the next step.

Slate guide image

2. Initiate processing of file

Now we can initiate the processing of a file. We simply need to pass the currently configured apiKey and an image file.

curl -X POST \
  https://api.aiconix.cloud/v1/cox/image/processUploadedFileAsync \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'file=@C:\Users\cb\Desktop\api-data-samples\image\President_Barack_Obama.jpg' \
  -F apiKey=a40c3fc2-585f-4bd0-90be-a95db46be026

3. Receive request id

After sending the request we receive the id of the request created for current processing as a plain text response.

e6162496-58c0-4d6d-a5d0-725b83039ec0

4. Poll for result

With the before received processID we can poll for results.

curl -X GET \
  https://api.aiconix.cloud/v1/cox/image/e6162496-58c0-4d6d-a5d0-725b83039ec0

5. Receive result

When aiconix service finishes processing for the provided image, results will be available in the following form:

[
    {
        "providers": [
            "aiconix"
        ],
        "requestId": "33c741db-a441-4b0d-acc7-4502386fe8a0",
        "mediaType": "Image",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "recognizedFaceResult": {
            "status": "Success",
            "recognizedFaces": [
                {
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.3916666805744171,
                                "y": 0.0625
                            },
                            {
                                "x": 0.3916666805744171,
                                "y": 0.4333333373069763
                            },
                            {
                                "x": 0.6541666388511658,
                                "y": 0.0625
                            },
                            {
                                "x": 0.6541666388511658,
                                "y": 0.4333333373069763
                            }
                        ]
                    },
                    "confidence": 0.9998527765274048,
                    "name": "Ernest_Allan_Hausmann"
                }
            ]
        },
        "faceIdentificationResult": {
            "status": "Success",
            "identifications": [
                "e48637d04aaf85711bef95515448dbae"
            ]
        }
    }
]

6. Define identity mapping

Once we receive the results with person identification, we are able to define naming for particular person. With applying name mapping, future processing of Face Recognotion and Faice Identification will be able to return names we defined for previously identified persons.

Body of the request should be consisted of apiKey that has Faice Identification feature selected and list of identity mappings. For each person we should provide Faice Identification id and corresponding name.

curl -X POST \
  https://api.aiconix.cloud/v1/cox/image/name \
  -H 'content-type: application/json' \
  -d '{
   "apiKey": "d10fef75-bfd5-45d3-9e7f-98c848c4b608",
   "identities":[
      {
         "id":"e48637d04aaf85711bef95515448dbae",
         "name":"Barack Obama"
      }]}'

7. Getting new results

For future images processing results where particular person is present, we should get correct recognition and naming according to the mapping we did in fifth step.

[
    {
        "providers": [
            "aiconix"
        ],
        "requestId": "33c741db-a441-4b0d-acc7-4502386fe8a0",
        "mediaType": "Image",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "recognizedFaceResult": {
            "status": "Success",
            "recognizedFaces": [
                {
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.3916666805744171,
                                "y": 0.0625
                            },
                            {
                                "x": 0.3916666805744171,
                                "y": 0.4333333373069763
                            },
                            {
                                "x": 0.6541666388511658,
                                "y": 0.0625
                            },
                            {
                                "x": 0.6541666388511658,
                                "y": 0.4333333373069763
                            }
                        ]
                    },
                    "confidence": 0.9998527765274048,
                    "name": "Barack Obama"
                }
            ]
        },
        "faceIdentificationResult": {
            "status": "Success",
            "identifications": [
                "e48637d04aaf85711bef95515448dbae"
            ]
        }
    }
]

8. Creating clusters

We are also able to group identified persons into clusters by using the following request:

curl -X POST \
  https://api.aiconix.cloud/v1/cox/image/cluster \
  -H 'content-type: application/json' \
  -d '{
   "apiKey": "d10fef75-bfd5-45d3-9e7f-98c848c4b608",
   "confidence": "0.7",
   "clustering_method": "ward",
   "ids":[
         "e48637d04aaf85711bef95515448dbae",
         "cf5ad6e7f6f61da51de98b63cfae89c1",
         "be6283d1b3d3b22b5f1d263173bf75cd"
   ]}'

Brand Detection

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/image/processUploadedFileAsync \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'file=@C:\Users\cb\Desktop\api-data-samples\image\President_Barack_Obama.jpg' \
  -F apiKey=a40c3fc2-585f-4bd0-90be-a95db46be026

Return

630742af-e826-4465-88a2-dd61a7388409

POST /cox/image/processUploadedFileAsync

Description

Returns detected popular product brands within an image.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
file byte[] Multipart request property data containing image that should be processed.

Response

Parameter Type Description
requestId string Unique request ID.

Poll Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/image/630742af-e826-4465-88a2-dd61a7388409 \
  -H 'content-type: application/json'

Return

[
    {
        "providers": [
            "Google"
        ],
        "requestId": "630742af-e826-4465-88a2-dd61a7388409",
        "mediaType": "Image",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "brandsResult": {
            "status": "Success",
            "brands": [
                {
                    "description": "Google",
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.05701754242181778,
                                "y": 0.12794612348079681
                            },
                            {
                                "x": 0.05701754242181778,
                                "y": 0.6868686676025391
                            },
                            {
                                "x": 0.6973684430122375,
                                "y": 0.12794612348079681
                            },
                            {
                                "x": 0.6973684430122375,
                                "y": 0.6868686676025391
                            }
                        ]
                    },
                    "confidence": 0.8284538984298706
                }
            ]
        }
    }
]

Poll Request

Request is made using requestId returned by aiconix when image processing was initiated.

Poll Response

Parameter Type Description
providers string[] Name of provider e.g. "Aiconix".
requestId string Unique request ID.
mediaType string Type of media sent to the provider e.g. Image.
operationMode string Operation mode selected in the API configuration. Can be "RawOverallResult", "BudgetResult" or "BestResults".
processingFinished bool Flag if processing is finished True or False.

Brand Detection Result

Parameter Type Description
status string Initiated when the request has been sent to the provider. Success when the result is available. More information to Status Codes is provided here.
featureError string Description of failure during processing.
brands object[] List of found brands.
description string Name of detected brand.
boundingPoly object[] List of vertices for the four corners of the polygon.
vertices object[] Contains x and y coordinates of polygon corners.
x number($double) X coordinate of the vertices [0-1].
y number($double) Y coordinate of the vertices [0-1].
confidence number($double) Confidence value of brand determination.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Color

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/image/processUploadedFileAsync \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'file=@C:\Users\cb\Desktop\api-data-samples\image\President_Barack_Obama.jpg' \
  -F apiKey=a40c3fc2-585f-4bd0-90be-a95db46be026

Return

630742af-e826-4465-88a2-dd61a7388409

POST /cox/image/processUploadedFileAsync

Description

Detects color shemes in processed image.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
file byte[] Multipart request property data containing image that should be processed.

Response

Parameter Type Description
requestId string Unique request ID.

Poll Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/image/630742af-e826-4465-88a2-dd61a7388409 \
  -H 'content-type: application/json'

Return

[
    {
        "providers": [
            "Microsoft"
        ],
        "requestId": "e1cf7bd8-ab0f-49b6-92f9-ca5d0cb3c502",
        "mediaType": "Image",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "colorsResult": {
            "status": "Success",
            "color": [
                {
                    "dominantColorForeground": "Blue",
                    "dominantColorBackground": "Blue",
                    "dominantColors": [
                        "Blue",
                        "Grey",
                        "Black"
                    ],
                    "accentColor": "BB2A10",
                    "isBWImg": false,
                    "colorTemperature": "-757"
                }
            ]
        }
    }
]

Poll Request

Request is made using requestId returned by aiconix when image processing was initiated.

Poll Response

Parameter Type Description
providers string[] Name of provider e.g. "Aiconix".
requestId string Unique request ID.
mediaType string Type of media sent to the provider e.g. Image.
operationMode string Operation mode selected in the API configuration. Can be "RawOverallResult", "BudgetResult" or "BestResults".
processingFinished bool Flag if processing is finished True or False.

Color Result

Parameter Type Description
status string Initiated when the request has been sent to the provider. Success when the result is available. More information to Status Codes is provided here.
featureError string Description of failure during processing.
color object[] List of foreground, background, and image colors for each sample image.
dominantColorForeground string Dominant foreground color found in the processed image.
dominantColorBackground string Dominant background color found in the processed image.
dominantColors string[] List of dominant colors found in processed the image.
accentColor string Accent color, as a hexadecimal HTML color value.
isBWImg boolean Computer Vision's black and white evaluation in the processed image. true or false.
colorTemperature number($integer) Light appearance provided by a light bulb.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Content Moderation

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/image/processUploadedFileAsync \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'file=@C:\Users\cb\Desktop\api-data-samples\image\President_Barack_Obama.jpg' \
  -F apiKey=a40c3fc2-585f-4bd0-90be-a95db46be026

Return

630742af-e826-4465-88a2-dd61a7388409

POST /cox/image/processUploadedFileAsync

Description

Categorization of explicit content e.g. adult, racy, medical, spoof, violence, etc.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
file byte[] Multipart request property data containing image that should be processed.

Response

Parameter Type Description
requestId string Unique request ID.

Poll Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/image/630742af-e826-4465-88a2-dd61a7388409 \
  -H 'content-type: application/json'

Return

[
    {
        "providers": [
            "aiconix"
        ],
        "requestId": "a69ab01b-1ac1-4c07-b21c-fdbd4d7e8e12",
        "mediaType": "Image",
        "operationMode": "BestResults",
        "processingFinished": true,
        "contentModerationResult": {
            "status": "Success",
            "contentModerations": [
                {
                    "description": "Gewalt",
                    "confidence": 0.2
                },
                {
                    "description": "Erwachsener",
                    "confidence": 0.2
                },
                {
                    "description": "Suggestiv",
                    "confidence": 0.4
                },
                {
                    "description": "Spoof",
                    "confidence": 0.4
                },
                {
                    "description": "medizinisch",
                    "confidence": 0.5
                }
            ],
            "originalContentModerations": [
                {
                    "description": "violence",
                    "confidence": 0.2
                },
                {
                    "description": "adult",
                    "confidence": 0.2
                },
                {
                    "description": "suggestive",
                    "confidence": 0.4
                },
                {
                    "description": "spoof",
                    "confidence": 0.4
                },
                {
                    "description": "medical",
                    "confidence": 0.5
                }
            ],
            "language": "de-DE"
        }
    }
]

Poll Request

Request is made using requestId returned by aiconix when image processing was initiated.

Poll Response

Parameter Type Description
providers string[] Name of provider e.g. "Aiconix".
requestId string Unique request ID.
mediaType string Type of media sent to the provider e.g. Image.
operationMode string Operation mode selected in the API configuration. Can be "RawOverallResult", "BudgetResult" or "BestResults".
processingFinished bool Flag if processing is finished True or False.

Content Moderation Result

Parameter Type Description
status string Initiated when the request has been sent to the provider. Success when the result is available. More information to Status Codes is provided here.
featureError string Description of failure during processing.
contentModerations object[] If translation was selected, this contains translated values for content moderations.
originalContentModerations object[] If a translation was selected, this contains the content information in their original language.
description string Content description.
confidence number($double) Numerical confidence in percentage.
language string Translation language

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Emotion Detection

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/image/processUploadedFileAsync \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'file=@C:\Users\cb\Desktop\api-data-samples\image\President_Barack_Obama.jpg' \
  -F apiKey=a40c3fc2-585f-4bd0-90be-a95db46be026

Return

630742af-e826-4465-88a2-dd61a7388409

POST /cox/image/processUploadedFileAsync

Description

Returns the emotion of the person in the image.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
file byte[] Multipart request property data containing image that should be processed.

Response

Parameter Type Description
requestId string Unique request ID.

Poll Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/image/630742af-e826-4465-88a2-dd61a7388409 \
  -H 'content-type: application/json'

Return

[
    {
        "providers": [
            "Sightcorp"
        ],
        "requestId": "47d28e45-f3d4-408e-87f5-74081d7e3d64",
        "mediaType": "Image",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "emotionResult": {
            "status": "Success",
            "emotions": [
                {
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.6022499799728394,
                                "y": 0.24567356705665588
                            },
                            {
                                "x": 0.6022499799728394,
                                "y": 0.39735323190689087
                            },
                            {
                                "x": 0.7137500047683716,
                                "y": 0.24567356705665588
                            },
                            {
                                "x": 0.7137500047683716,
                                "y": 0.39735323190689087
                            }
                        ]
                    },
                    "emotionProbabilities": [
                        {
                            "emotion": "Happiness",
                            "confidence": 0.10999999940395355
                        },
                        {
                            "emotion": "Surprise",
                            "confidence": 0.11999999731779099
                        },
                        {
                            "emotion": "Anger",
                            "confidence": 0.20000000298023224
                        },
                        {
                            "emotion": "Disgust",
                            "confidence": 0.25999999046325684
                        },
                        {
                            "emotion": "Fear",
                            "confidence": 0.07000000029802322
                        },
                        {
                            "emotion": "Sadness",
                            "confidence": 0.18000000715255737
                        }
                    ]
                }
            ]
        }
    }
]

Poll Request

Request is made using requestId returned by aiconix when image processing was initiated.

Poll Response

Parameter Type Description
providers string[] Name of provider e.g. "Aiconix".
requestId string Unique request ID.
mediaType string Type of media sent to the provider e.g. Image.
operationMode string Operation mode selected in the API configuration. Can be "RawOverallResult", "BudgetResult" or "BestResults".
processingFinished bool Flag if processing is finished True or False.

Emotion Detection Result

Parameter Type Description
status string Initiated when the request has been sent to the provider. Success when the result is available. More information to Status Codes is provided here.
featureError string Description of failure during processing.
emotions object[] List of texts recognized in the image.
boundingPoly object[] List of vertices which are surrounding the text labels.
vertices {x,y} List of x and y tuples for the vertices.
x number($double) X coordinate of the vertices.
y number($double) Y coordinate of the vertices.
emotionProbabilities object[] List of emotion tags and confidence values.
emotion string Emotion describing the face of a person.
confidence number($double) Percentage of confidence [0-1].

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Face Detection

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/image/processUploadedFileAsync \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'file=@C:\Users\cb\Desktop\api-data-samples\image\President_Barack_Obama.jpg' \
  -F apiKey=a40c3fc2-585f-4bd0-90be-a95db46be026

Return

630742af-e826-4465-88a2-dd61a7388409

POST /cox/image/processUploadedFileAsync

Description

Returns polygons for found faces in the image.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
file byte[] Multipart request property data containing image that should be processed.

Response

Parameter Type Description
requestId string Unique request ID.

Poll Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/image/630742af-e826-4465-88a2-dd61a7388409 \
  -H 'content-type: application/json'

Return

[
    {
        "providers": [
            "aiconix"
        ],
        "requestId": "d5a8cdec-4a65-416a-a16c-5360e58312c9",
        "mediaType": "Image",
        "operationMode": "BestResults",
        "processingFinished": true,
        "faceDetectionResult": {
            "status": "Partial",
            "detectedFaces": [
                {
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.3885209858417511,
                                "y": 0.09271523356437683
                            },
                            {
                                "x": 0.3885209858417511,
                                "y": 0.30960264801979065
                            },
                            {
                                "x": 0.6384785175323486,
                                "y": 0.09271523356437683
                            },
                            {
                                "x": 0.6384785175323486,
                                "y": 0.30960264801979065
                            }
                        ]
                    },
                    "confidence": 1
                }
            ]
        }
    }
]

Poll Request

Request is made using requestId returned by aiconix when image processing was initiated.

Poll Response

Parameter Type Description
providers string[] Name of provider e.g. "Aiconix".
requestId string Unique request ID.
mediaType string Type of media sent to the provider e.g. Image.
operationMode string Operation mode selected in the API configuration. Can be "RawOverallResult", "BudgetResult" or "BestResults".
processingFinished bool Flag if processing is finished True or False.

Face Detection Result

Parameter Type Description
status string Initiated when the request has been sent to the provider. Success when the result is available. More information to Status Codes is provided here.
featureError string Description of failure during processing.
detectedFaces object[] List of faces found.
boundingPoly object[] List of vertices for the four corners of the polygon.
vertices object[] Contains x and y coordinates of polygon corners.
x number($double) X coordinate of the vertices [0-1].
y number($double) Y coordinate of the vertices [0-1].
confidence number($double) Confidence value of face detection.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Face Recognition

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/image/processUploadedFileAsync \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'file=@C:\Users\cb\Desktop\api-data-samples\image\President_Barack_Obama.jpg' \
  -F apiKey=a40c3fc2-585f-4bd0-90be-a95db46be026

Return

630742af-e826-4465-88a2-dd61a7388409

POST /cox/image/processUploadedFileAsync

Description

Returns name of person and polygons for found face in the image.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
file byte[] Multipart request property data containing image that should be processed.

Response

Parameter Type Description
requestId string Unique request ID.

Poll Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/image/630742af-e826-4465-88a2-dd61a7388409 \
  -H 'content-type: application/json'

Return

[
    {
        "providers": [
            "Amazon"
        ],
        "requestId": "7ead538d-05c4-43bf-97a5-96ee07ac5540",
        "mediaType": "Image",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "recognizedFaceResult": {
            "status": "Success",
            "recognizedFaces": [
                {
                    "name": "Barack Obama",
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.3181818127632141,
                                "y": 0.06181818246841431
                            },
                            {
                                "x": 0.3181818127632141,
                                "y": 0.3418181836605072
                            },
                            {
                                "x": 0.6681817770004272,
                                "y": 0.06181818246841431
                            },
                            {
                                "x": 0.6681817770004272,
                                "y": 0.3418181836605072
                            }
                        ]
                    },
                    "confidence": 0.9999969601631165
                }
            ]
        }
    }
]

Poll Request

Request is made using requestId returned by aiconix when image processing was initiated.

Poll Response

Parameter Type Description
providers string[] Name of provider e.g. "Aiconix".
requestId string Unique request ID.
mediaType string Type of media sent to the provider e.g. Image.
operationMode string Operation mode selected in the API configuration. Can be "RawOverallResult", "BudgetResult" or "BestResults".
processingFinished bool Flag if processing is finished True or False.

Recognized Face Result

Parameter Type Description
status string Initiated when the request has been sent to the provider. Success when the result is available. More information to Status Codes is provided here.
featureError string Description of failure during processing.
recognizedFaces object[] List of faces found.
name string Name of person.
boundingPoly object[] List of vertices for the four corners of the polygon.
vertices object[] Contains x and y coordinates of polygon corners.
x number($double) X coordinate of the vertices [0-1].
y number($double) Y coordinate of the vertices [0-1].
confidence number($double) Confidence value of face recognition.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Faice Identification & Clustering

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/image/processUploadedFileAsync \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'file=@C:\Users\cb\Desktop\api-data-samples\image\President_Barack_Obama.jpg' \
  -F apiKey=a40c3fc2-585f-4bd0-90be-a95db46be026

Return

630742af-e826-4465-88a2-dd61a7388409

Faice Identification - Faice IDs

POST /cox/image/processUploadedFileAsync

Description

Returns an id for every face found in the image. For exact the same image the returned id's should always be the same for the same face.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
file byte[] Multipart request property data containing image that should be processed.

Response

Parameter Type Description
requestId string Unique request ID.

Poll Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/image/630742af-e826-4465-88a2-dd61a7388409 \
  -H 'content-type: application/json'

Return

[
     {
     "providers": ["aiconix"],
     "requestId": "0dd8ce01-912a-427d-8559-ca231c4e4c0c",
     "mediaType": "Image",
     "operationMode": "RawOverallResult",
     "processingFinished": true,
     "faceIdentificationResult":       {
        "status": "Success",
        "identifications": ["8511bca297ce4547689bb620c9a3fb22"]
     }
  }
]

Poll Request

Request is made using requestId returned by aiconix when image processing was initiated.

Poll Response

Parameter Type Description
providers string[] Name of provider e.g. "Aiconix".
requestId string Unique request ID.
mediaType string Type of media sent to the provider e.g. Image.
operationMode string Operation mode selected in the API configuration. Can be "RawOverallResult", "BudgetResult" or "BestResults".
processingFinished bool Flag if processing is finished True or False.

Faice Identification Result

Parameter Type Description
status string Initiated when the request has been sent to the provider. Success when the result is available. More information to Status Codes is provided here.
featureError string Description of failure during processing.
identifications string[] Id for every face found in the image.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Request

curl -X POST \
  https://api.aiconix.cloud/cox/image/name \
  -H 'Content-Type: application/json' \
  -d '{
   "apiKey": "d10fef75-bfd5-45d3-9e7f-98c848c4b608",
   "identities":[
      {
         "id":"2a4afe231caead1cdd7c1710704d4008",
         "name":"Cameron Diaz"
      },
      {
         "id":"81bd88a9f8f2642ec9aea5d2e3e4253c",
         "name":"Bruce Willis"
      },
      {
        "id": "dcb8e1efb8cee418f041a74e02e5918a",
        "name": "Rafael Van Der Vaart"
      }]}'

Return

{
    "results": [
        {
            "id": "2a4afe231caead1cdd7c1710704d4008",
            "status": "Failed",
            "error": "wrong id"
        },
        {
            "id": "81bd88a9f8f2642ec9aea5d2e3e4253c",
            "status": "Failed",
            "error": "wrong id"
        },
        {
            "id": "dcb8e1efb8cee418f041a74e02e5918a",
            "status": "Success"
        }
    ]
}

Faice Identification - Assign Names

POST /cox/image/name

Description

Set mapping of id related to recognized person to person name.

Body

Parameter Type Description
apiKey string Api key that has Faice Identification feature selected.
identities object[] Array of identities with id to name mappings.
identities[n].id string Id of the recognized face, received for FaceIdentification feature result.
identities[n].name string Name of the person.

Response

Parameter Type Description
results object[] Result of mapping per each ID sent in request.
results[n].id string Recognized face ID.
results[n].status string Indication if name mapping is applied. Status Success or Failed.
results[n].error string Reason in case of mapping failure.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Request

curl -X POST \
  http://api.aiconix.cloud/cox/image/cluster \
  -H 'Content-Type: application/json' \
  -d ' {
   "apiKey": "d10fef75-bfd5-45d3-9e7f-98c848c4b608",
   "confidence": "0.7",
   "clustering_method": "ward",
   "ids":[
         "cf5ad6e7f6f61da51de98b63cfaveec1",
         "cf5ad6e7f6f61da51de98b63cfae89c1",
         "be6283d1b3d3b22b5f1d263173bf75cd"
   ]
}'

Return

{
   "results":[
      {
         "id":"cf5ad6e7f6f61da51de98b63cfaveec1",
         "status":"Failed",
         "error":"The id does not exist in our DB"
      },
      {
         "id":"cf5ad6e7f6f61da51de98b63cfae89c1",
         "status":"Success",
         "cluster":0
      },
      {
         "id":"be6283d1b3d3b22b5f1d263173bf75cd",
         "status":"Success",
         "cluster":0
      }
   ]
}

Faice Identification - Cluster Faces

POST /cox/image/cluster

Description

Group identified persons into clusters.

Body

Parameter Type Description
apiKey string Api key that has Faice Identification feature selected.
confidence number($double) Decimal value between 0-1. (Optional)
clustering_method string Clustering method. Valid values are 'ward' (least accurate, fastest), 'dbscan' and 'chinese_whispers' (most accurate, slowest)"
ids string[] Array of identified person ids.

Response

Parameter Type Description
results object[] Result of creating clusters from provided IDs sent in request.
results[n].id string Recognized face ID.
results[n].status string Indication if id became a part of one cluster. Status Success or Failed.
results[n].error string Reason in case of clustering failure.
results[n].cluster integer Cluster number.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Facial Attributes

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/image/processUploadedFileAsync \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'file=@C:\Users\cb\Desktop\api-data-samples\image\President_Barack_Obama.jpg' \
  -F apiKey=a40c3fc2-585f-4bd0-90be-a95db46be026

Return

630742af-e826-4465-88a2-dd61a7388409

POST /cox/image/processUploadedFileAsync

Description

Returns facial attributes for found faces in the image.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
file byte[] Multipart request property data containing image that should be processed.

Response

Parameter Type Description
requestId string Unique request ID.

Poll Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/image/630742af-e826-4465-88a2-dd61a7388409 \
  -H 'content-type: application/json'

Return

[
    {
        "providers": [
            "Amazon"
        ],
        "requestId": "9a5551bc-74c9-4f75-9121-a21e56734764",
        "mediaType": "Image",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "facialAttributesResult": {
            "status": "Success",
            "facialAttributes": [
                {
                    "ageRange": {
                        "low": 22,
                        "high": 34
                    },
                    "beard": {
                        "hasBeard": true,
                        "confidence": 0.5209843516349792
                    },
                    "eyeglasses": {
                        "hasEyeglasses": false,
                        "confidence": 0.942704975605011
                    },
                    "eyeOpen": {
                        "confidence": 0.988126814365387,
                        "eyeOpen": true
                    },
                    "gender": {
                        "gender": "Male",
                        "confidence": 0.9915726184844971
                    },
                    "mouthOpen": {
                        "confidence": 0.9941784739494324,
                        "mouthOpen": false
                    },
                    "mustache": {
                        "hasMustache": false,
                        "confidence": 0.9619507789611816
                    },
                    "pose": {
                        "pitch": -4.754584,
                        "roll": 4.775464,
                        "yaw": -3.4301455
                    },
                    "smile": {
                        "hasSmile": false,
                        "confidence": 0.9734138250350952
                    },
                    "sunglasses": {
                        "hasSunglasses": false,
                        "confidence": 0.9777885675430298
                    },
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.15429893136024475,
                                "y": 0.29966533184051514
                            },
                            {
                                "x": 0.15429893136024475,
                                "y": 0.7159667015075684
                            },
                            {
                                "x": 0.43218204379081726,
                                "y": 0.29966533184051514
                            },
                            {
                                "x": 0.43218204379081726,
                                "y": 0.7159667015075684
                            }
                        ]
                    }
                },
                {
                    "ageRange": {
                        "low": 13,
                        "high": 25
                    },
                    "beard": {
                        "hasBeard": false,
                        "confidence": 0.9989632964134216
                    },
                    "eyeglasses": {
                        "hasEyeglasses": false,
                        "confidence": 0.997433066368103
                    },
                    "eyeOpen": {
                        "confidence": 0.9988717436790466,
                        "eyeOpen": true
                    },
                    "gender": {
                        "gender": "Female",
                        "confidence": 0.9996592998504639
                    },
                    "mouthOpen": {
                        "confidence": 0.9900257587432861,
                        "mouthOpen": false
                    },
                    "mustache": {
                        "hasMustache": false,
                        "confidence": 0.9996470808982849
                    },
                    "pose": {
                        "pitch": -42.025444,
                        "roll": -26.038641,
                        "yaw": -3.9953296
                    },
                    "smile": {
                        "hasSmile": true,
                        "confidence": 0.7326675653457642
                    },
                    "sunglasses": {
                        "hasSunglasses": false,
                        "confidence": 0.9989063739776611
                    },
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.48106345534324646,
                                "y": 0.46429646015167236
                            },
                            {
                                "x": 0.48106345534324646,
                                "y": 0.7311074733734131
                            },
                            {
                                "x": 0.735027015209198,
                                "y": 0.46429646015167236
                            },
                            {
                                "x": 0.735027015209198,
                                "y": 0.7311074733734131
                            }
                        ]
                    }
                }
            ]
        }
    }
]

Poll Request

Request is made using requestId returned by aiconix when image processing was initiated.

Poll Response

Parameter Type Description
providers string[] Name of provider e.g. "Aiconix".
requestId string Unique request ID.
mediaType string Type of media sent to the provider e.g. Image.
operationMode string Operation mode selected in the API configuration. Can be "RawOverallResult", "BudgetResult" or "BestResults".
processingFinished bool Flag if processing is finished True or False.

Face Detection Result

Parameter Type Description
status string Initiated when the request has been sent to the provider. Success when the result is available. More information to Status Codes is provided here.
featureError string Description of failure during processing.
facialAttributes object[] List of found facial attributes.
ageRange object The estimated age range, in years, for the face.
low number($integer) The lowest estimated age.
high number($integer) The highest estimated age.
beard object Indicates whether or not the face has a beard, and the confidence level in the determination.
hasBeard boolean Indicates whether or not the face has a beard.
confidence number($double) Confidence value of beard determination.
eyeglasses object Indicates whether or not the face is wearing eye glasses, and the confidence level in the determination.
hasEyeglasses boolean Indicates whether or not the face is wearing eye glasses.
confidence number($double) Confidence value of eye glasses determination.
eyeOpen object Indicates whether or not the eyes on the face are open, and the confidence level in the determination.
eyeOpen boolean Indicates whether or not the eyes on the face are open.
confidence number($double) Confidence value of eyes open determination.
gender object Gender of the face and the confidence level in the determination.
gender string Gender of the face. Possible values are male or female.
confidence number($double) Confidence value of gender determination.
mouthOpen object Indicates whether or not the mouth on the face is open, and the confidence level in the determination.
mouthOpen boolean Indicates whether or not the mouth on the face is open.
confidence number($double) Confidence value of mouth open determination.
mustache object Indicates whether or not the face has a mustache, and the confidence level in the determination.
hasMustache boolean Indicates whether or not the face has a mustache.
confidence number($double) Confidence value of mustache determination.
pose object Indicates the pose of the face as determined by its pitch, roll, and yaw.
pitch number($double) Value representing the face rotation on the pitch axis.
roll number($double) Value representing the face rotation on the roll axis.
yaw number($double) Value representing the face rotation on the yaw axis.
smile object Indicates whether or not the face is smiling, and the confidence level in the determination.
hasSmile boolean Indicates whether or not the face is smiling.
confidence number($double) Confidence value of smile determination.
sunglasses object Indicates whether or not the face is wearing sunglasses, and the confidence level in the determination..
hasSunglasses boolean Indicates whether or not the face is wearing sunglasses.
confidence number($double) Confidence value of sunglasses determination.
boundingPoly object[] List of vertices for the four corners of the polygon.
vertices object[] Contains x and y coordinates of polygon corners.
x number($double) X coordinate of the vertices [0-1].
y number($double) Y coordinate of the vertices [0-1].

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Facial Landmarks Detection

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/image/processUploadedFileAsync \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'file=@C:\Users\cb\Desktop\api-data-samples\image\President_Barack_Obama.jpg' \
  -F apiKey=a40c3fc2-585f-4bd0-90be-a95db46be026

Return

630742af-e826-4465-88a2-dd61a7388409

POST /cox/image/processUploadedFileAsync

Description

Returns the facial landmarks of the person in the image.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
file byte[] Multipart request property data containing image that should be processed.

Response

Parameter Type Description
requestId string Unique request ID.

Poll Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/image/630742af-e826-4465-88a2-dd61a7388409 \
  -H 'content-type: application/json'

Return

[
    {
        "providers": [
            "Amazon"
        ],
        "requestId": "47d28e45-f3d4-408e-87f5-74081d7e3d64",
        "mediaType": "Image",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "facialLandmarksResult": {
            "status": "Success",
            "landmarkFaces": [
                {
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.6022499799728394,
                                "y": 0.24567356705665588
                            },
                            {
                                "x": 0.6022499799728394,
                                "y": 0.39735323190689087
                            },
                            {
                                "x": 0.7137500047683716,
                                "y": 0.24567356705665588
                            },
                            {
                                "x": 0.7137500047683716,
                                "y": 0.39735323190689087
                            }
                        ]
                    },
                    "facialLandmarks": [
                        {
                            "landmarkType": "eyeLeft",
                            "position": {
                                "x": 0.7102732062339783,
                                "y": 0.3526104986667633
                            }
                        },
                        {
                            "landmarkType": "eyeRight",
                            "position": {
                                "x": 0.8684776425361633,
                                "y": 0.28801581263542175
                            }
                        },
                        {
                            "landmarkType": "mouthLeft",
                            "position": {
                                "x": 0.78423011302948,
                                "y": 0.5607832670211792
                            }
                        },
                        {
                            "landmarkType": "mouthRight",
                            "position": {
                                "x": 0.916346549987793,
                                "y": 0.5088289976119995
                            }
                        },
                        {
                            "landmarkType": "nose",
                            "position": {
                                "x": 0.7979027628898621,
                                "y": 0.4508737027645111
                            }
                        }
                    ]
                }
            ]
        }
    }
]

Poll Request

Request is made using requestId returned by aiconix when image processing was initiated.

Poll Response

Parameter Type Description
providers string[] Name of provider e.g. "Aiconix".
requestId string Unique request ID.
mediaType string Type of media sent to the provider e.g. Image.
operationMode string Operation mode selected in the API configuration. Can be "RawOverallResult", "BudgetResult" or "BestResults".
processingFinished bool Flag if processing is finished True or False.

Facial Landmarks Detection Result

Parameter Type Description
status string Initiated when the request has been sent to the provider. Success when the result is available. More information to Status Codes is provided here.
featureError string Description of failure during processing.
landmarkFaces object[] landmarksFace list, contains landmarks for all detected faces.
boundingPoly object[] Contains vertices information about detected face.
vertices {x,y} List of x and y tuples for the vertices.
x (vertex) number($double) X coordinate of the vertices.
y (vertex) number($double) Y coordinate of the vertices.
facialLandmarks object[] Contains data about every detected landmark on a face.
landmarkType string Type of landmark.
position {x,y} Position of landmark on a frame.
x (position) number($double) X coordinate of the vertices.
y (position) number($double) Y coordinate of the vertices.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Hair Color

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/image/processUploadedFileAsync \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'file=@C:\Users\cb\Desktop\api-data-samples\image\President_Barack_Obama.jpg' \
  -F apiKey=a40c3fc2-585f-4bd0-90be-a95db46be026

Return

630742af-e826-4465-88a2-dd61a7388409

POST /cox/image/processUploadedFileAsync

Description

Hair color on person found in the image.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
file byte[] Multipart request property data containing image that should be processed.

Response

Parameter Type Description
requestId string Unique request ID.

Poll Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/image/630742af-e826-4465-88a2-dd61a7388409 \
  -H 'content-type: application/json'

Return

[
    {
        "providers": [
            "Microsoft"
        ],
        "requestId": "5b4ad22e-2539-4e44-8dc0-ba2e0169a8c4",
        "mediaType": "Image",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "hairColorsResult": {
            "status": "Success",
            "hairColors": [
                {
                    "color": "Brown",
                    "confidence": 1.0
                },
                {
                    "color": "Red",
                    "confidence": 0.56
                },
                {
                    "color": "Blond",
                    "confidence": 0.48
                },
                {
                    "color": "Black",
                    "confidence": 0.17
                },
                {
                    "color": "Gray",
                    "confidence": 0.09
                },
                {
                    "color": "Other",
                    "confidence": 0.04
                }
            ]
        }
    }
]

Poll Request

Request is made using requestId returned by aiconix when image processing was initiated.

Poll Response

Parameter Type Description
providers string[] Name of provider e.g. "Aiconix".
requestId string Unique request ID.
mediaType string Type of media sent to the provider e.g. Image.
operationMode string Operation mode selected in the API configuration. Can be "RawOverallResult", "BudgetResult" or "BestResults".
processingFinished bool Flag if processing is finished True or False.

Hair Color Result

Parameter Type Description
status string Initiated when the request has been sent to the provider. Success when the result is available. More information to Status Codes is provided here.
featureError string Description of failure during processing.
hairColors object[] List of hair colors found on image.
color string Hair color e.g. 'Blond', 'Black', 'Brown'.
confidence number($double) Numerical confidence in percentage.

Label Detection

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/image/processUploadedFileAsync \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'file=@C:\Users\cb\Desktop\api-data-samples\image\President_Barack_Obama.jpg' \
  -F apiKey=a40c3fc2-585f-4bd0-90be-a95db46be026

Return

630742af-e826-4465-88a2-dd61a7388409

POST /cox/image/processUploadedFileAsync

Description

Return specific features which can be used to identify an image.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
file byte[] Multipart request property data containing image that should be processed.

Response

Parameter Type Description
requestId string Unique request ID.

Poll Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/image/630742af-e826-4465-88a2-dd61a7388409 \
  -H 'content-type: application/json'

Return

[
    {
        "providers": [
            "aiconix"
        ],
        "requestId": "916210a1-4445-41fd-bc69-4731f2610ebb",
        "mediaType": "Image",
        "operationMode": "BestResults",
        "processingFinished": true,
        "labelResult": {
            "status": "Success",
            "labels": [
                {
                    "description": "Straßenschild",
                    "confidence": 0.8271082305908203
                },
                {
                    "description": "Schild",
                    "confidence": 0.9998051427697969
                },
                {
                    "description": "Beschilderung",
                    "confidence": 0.9068593978881836
                },
                {
                    "description": "Straße",
                    "confidence": 0.9999631065189272
                }
            ],
            "originalLabels": [
                {
                    "description": "road sign",
                    "confidence": 0.8271082305908203
                },
                {
                    "description": "sign",
                    "confidence": 0.9998051427697969
                },
                {
                    "description": "signage",
                    "confidence": 0.9068593978881836
                },
                {
                    "description": "road",
                    "confidence": 0.9999631065189272
                }
            ],
            "language": "de-DE"
        }
    }
]

Poll Request

Request is made using requestId returned by aiconix when image processing was initiated.

Poll Response

Parameter Type Description
providers string[] Name of provider e.g. "Aiconix".
requestId string Unique request ID.
mediaType string Type of media sent to the provider e.g. Image.
operationMode string Operation mode selected in the API configuration. Can be "RawOverallResult", "BudgetResult" or "BestResults".
processingFinished bool Flag if processing is finished True or False.

Label Result

Parameter Type Description
status string Initiated when the request has been sent to the provider. Success when the result is available. More information to Status Codes is provided here.
featureError string Description of failure during processing.
labels object[] List of labels found.
originalLabels object[] If a translation was selected, this contains the labels in their original language.
confidence number($double) Percentage of confidence [0-1].
description string A describing label for the content in the image e.g text, logo, graphics, trademark, etc.
language string Label language

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Landmarks & Places

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/image/processUploadedFileAsync \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'file=@C:\Users\cb\Desktop\api-data-samples\image\President_Barack_Obama.jpg' \
  -F apiKey=a40c3fc2-585f-4bd0-90be-a95db46be026

Return

630742af-e826-4465-88a2-dd61a7388409

POST /cox/image/processUploadedFileAsync

Description

Returns detected places in an image by some landmarks.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
file byte[] Multipart request property data containing image that should be processed.

Response

Parameter Type Description
requestId string Unique request ID.

Poll Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/image/630742af-e826-4465-88a2-dd61a7388409 \
  -H 'content-type: application/json'

Return

[
    {
        "providers": [
            "Google"
        ],
        "requestId": "07a5d98e-7036-4045-b4cd-d6a4d20d2ed3",
        "mediaType": "Image",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "placeLandmarksResult": {
            "status": "Success",
            "places": [
                {
                    "description": "Novi Sad city centre",
                    "confidence": 0.9098294973373413,
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.29436689615249634,
                                "y": 0.3795264661312103
                            },
                            {
                                "x": 0.29436689615249634,
                                "y": 0.6549736857414246
                            },
                            {
                                "x": 0.7083129286766052,
                                "y": 0.3795264661312103
                            },
                            {
                                "x": 0.7083129286766052,
                                "y": 0.6549736857414246
                            }
                        ]
                    }
                    "locations" : [
                            {
                                 "latitude" : 44.52,
                                 "longitude" : 22.22
                            }
                     ]
                }
            ]
        }
    }
]

Poll Request

Request is made using requestId returned by aiconix when image processing was initiated.

Poll Response

Parameter Type Description
providers string[] Name of provider e.g. "Aiconix".
requestId string Unique request ID.
mediaType string Type of media sent to the provider e.g. Image.
operationMode string Operation mode selected in the API configuration. Can be "RawOverallResult", "BudgetResult" or "BestResults".
processingFinished bool Flag if processing is finished True or False.

Place Landmarks Result

Parameter Type Description
status string Initiated when the request has been sent to the provider. Success when the result is available. More information to Status Codes is provided here.
featureError string Description of failure during processing.
places object[] List of detected places.
description string Description of detected places.
boundingPoly object[] List of vertices for the four corners of the polygon.
vertices object[] Contains x and y coordinates of polygon corners.
x number($double) X coordinate of the vertices [0-1].
y number($double) Y coordinate of the vertices [0-1].
confidence number($double) Confidence value of object determination.
locations object[] Locations of places on geo map.
latitude number($double) Latitude value
longitude number($double) Longitude value

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Object Localizer

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/image/processUploadedFileAsync \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'file=@C:\Users\cb\Desktop\api-data-samples\image\President_Barack_Obama.jpg' \
  -F apiKey=a40c3fc2-585f-4bd0-90be-a95db46be026

Return

630742af-e826-4465-88a2-dd61a7388409

POST /cox/image/processUploadedFileAsync

Description

Returns detected objects in an image.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
file byte[] Multipart request property data containing image that should be processed.

Response

Parameter Type Description
requestId string Unique request ID.

Poll Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/image/630742af-e826-4465-88a2-dd61a7388409 \
  -H 'content-type: application/json'

Return

[
    {
        "providers": [
            "Google"
        ],
        "requestId": "07a5d98e-7036-4045-b4cd-d6a4d20d2ed3",
        "mediaType": "Image",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "objectLocalizerResult": {
            "status": "Success",
            "objects": [
                {
                    "description": "Car",
                    "confidence": 0.9098294973373413,
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.29436689615249634,
                                "y": 0.3795264661312103
                            },
                            {
                                "x": 0.29436689615249634,
                                "y": 0.6549736857414246
                            },
                            {
                                "x": 0.7083129286766052,
                                "y": 0.3795264661312103
                            },
                            {
                                "x": 0.7083129286766052,
                                "y": 0.6549736857414246
                            }
                        ]
                    }
                },
                {
                    "description": "Wheel",
                    "confidence": 0.8807717561721802,
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.4616889953613281,
                                "y": 0.4997922480106354
                            },
                            {
                                "x": 0.4616889953613281,
                                "y": 0.6503865718841553
                            },
                            {
                                "x": 0.5543482899665833,
                                "y": 0.4997922480106354
                            },
                            {
                                "x": 0.5543482899665833,
                                "y": 0.6503865718841553
                            }
                        ]
                    }
                },
                {
                    "description": "Tire",
                    "confidence": 0.7062026858329773,
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.6449424624443054,
                                "y": 0.5126665234565735
                            },
                            {
                                "x": 0.6449424624443054,
                                "y": 0.6458868384361267
                            },
                            {
                                "x": 0.7087364196777344,
                                "y": 0.5126665234565735
                            },
                            {
                                "x": 0.7087364196777344,
                                "y": 0.6458868384361267
                            }
                        ]
                    }
                }
            ]
        }
    }
]

Poll Request

Request is made using requestId returned by aiconix when image processing was initiated.

Poll Response

Parameter Type Description
providers string[] Name of provider e.g. "Aiconix".
requestId string Unique request ID.
mediaType string Type of media sent to the provider e.g. Image.
operationMode string Operation mode selected in the API configuration. Can be "RawOverallResult", "BudgetResult" or "BestResults".
processingFinished bool Flag if processing is finished True or False.

Object Detection Result

Parameter Type Description
status string Initiated when the request has been sent to the provider. Success when the result is available. More information to Status Codes is provided here.
featureError string Description of failure during processing.
objects object[] List of detected objects.
description string Description of detected object.
boundingPoly object[] List of vertices for the four corners of the polygon.
vertices object[] Contains x and y coordinates of polygon corners.
x number($double) X coordinate of the vertices [0-1].
y number($double) Y coordinate of the vertices [0-1].
confidence number($double) Confidence value of object determination.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Optical Character Recognition

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/image/processUploadedFileAsync \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'file=@C:\Users\cb\Desktop\api-data-samples\image\President_Barack_Obama.jpg' \
  -F apiKey=a40c3fc2-585f-4bd0-90be-a95db46be026

Return

630742af-e826-4465-88a2-dd61a7388409

POST /cox/image/processUploadedFileAsync

Description

Returns the text of the label in the image.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
file byte[] Multipart request property data containing image that should be processed.

Response

Parameter Type Description
requestId string Unique request ID.

Poll Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/image/630742af-e826-4465-88a2-dd61a7388409 \
  -H 'content-type: application/json'

Return

[
    {
        "providers": [
            "Amazon"
        ],
        "requestId": "aca5e7f7-4d83-4627-98ee-5eaf14ac9e4c",
        "mediaType": "Image",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "textRecognitionResult": {
            "status": "Success",
            "textRecognitions": [
                {
                    "description": "adidas",
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.0714285746216774,
                                "y": 0.6185185313224792
                            },
                            {
                                "x": 0.0714285746216774,
                                "y": 0.9444444179534912
                            },
                            {
                                "x": 0.9357143044471741,
                                "y": 0.6185185313224792
                            },
                            {
                                "x": 0.9357143044471741,
                                "y": 0.9444444179534912
                            }
                        ]
                    }
                }
            ]
        }
    }
]

Poll Request

Request is made using requestId returned by aiconix when image processing was initiated.

Poll Response

Parameter Type Description
providers string[] Name of provider e.g. "Aiconix".
requestId string Unique request ID.
mediaType string Type of media sent to the provider e.g. Image.
operationMode string Operation mode selected in the API configuration. Can be "RawOverallResult", "BudgetResult" or "BestResults".
processingFinished bool Flag if processing is finished True or False.

Text Recognition Result

Parameter Type Description
status string Initiated when the request has been sent to the provider. Success when the result is available. More information to Status Codes is provided here.
featureError string Description of failure during processing.
textRecognitions object[] List of texts recognized in the image.
description string Recognized text.
boundingPoly object[] List of vertices which are surrounding the text labels.
vertices {x,y} List of x and y tuples for the vertices.
x number($double) X coordinate of the vertices.
y number($double) Y coordinate of the vertices.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Pose Detection

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/image/processUploadedFileAsync \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'file=@C:\Users\cb\Desktop\api-data-samples\image\President_Barack_Obama.jpg' \
  -F apiKey=a40c3fc2-585f-4bd0-90be-a95db46be026

Return

630742af-e826-4465-88a2-dd61a7388409

POST /cox/image/processUploadedFileAsync

Description

Returns face, person, right hand and left hand for found person in the image.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
file byte[] Multipart request property data containing image that should be processed.

Response

Parameter Type Description
requestId string Unique request ID.

Poll Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/image/630742af-e826-4465-88a2-dd61a7388409 \
  -H 'content-type: application/json'

Return

[
    {
        "providers": [
            "aiconix"
        ],
        "requestId": "b4ed2487-615b-422f-b1d3-42475b5609d1",
        "mediaType": "Image",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "poseResult": {
            "status": "Success",
            "poses": [
                {
                    "face": [
                        {
                            "x": 482.885,
                            "y": 343.521,
                            "score": 0.80404
                        },
                        {
                            "x": 481.05,
                            "y": 352.696,
                            "score": 0.823125
                        },
                        {
                            "x": 481.05,
                            "y": 363.247,
                            "score": 0.733141
                        },
                        {
                            "x": 481.509,
                            "y": 374.257,
                            "score": 0.630143
                        }
                    ],
                    "person": [
                        {
                            "x": 500.021,
                            "y": 364.925,
                            "score": 0.888012
                        },
                        {
                            "x": 512.419,
                            "y": 471.438,
                            "score": 0.892208
                        }
                    ],
                    "rightHand": [
                        {
                            "x": 387.599,
                            "y": 747.396,
                            "score": 0.539277
                        },
                        {
                            "x": 412.999,
                            "y": 750.218,
                            "score": 0.628828
                        },
                        {
                            "x": 437.835,
                            "y": 764.329,
                            "score": 0.914351
                        }
                    ],
                    "leftHand": [
                        {
                            "x": 612.766,
                            "y": 558.786,
                            "score": 0.542876
                        },
                        {
                            "x": 606.866,
                            "y": 537.807,
                            "score": 0.587398
                        }
                    ]
                }
            ]
        }
    }
]

Poll Request

Request is made using requestId returned by aiconix when image processing was initiated.

Poll Response

Parameter Type Description
providers string[] Name of provider e.g. "Aiconix".
requestId string Unique request ID.
mediaType string Type of media sent to the provider e.g. Image.
operationMode string Operation mode selected in the API configuration. Can be "RawOverallResult", "BudgetResult" or "BestResults".
processingFinished bool Flag if processing is finished True or False.

Pose Detection Result

Parameter Type Description
status string Initiated when the request has been sent to the provider. Success when the result is available. More information to Status Codes is provided here.
featureError string Description of failure during processing.
poses object[] List of poses. Can be Face, Person, rightHand and leftHand.
x number($double) X coordinate of the vertices in pixels.
y number($double) Y coordinate of the vertices in pixels.
score number($double) Percentage of score [0-1].

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Shot Size

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/image/processUploadedFileAsync \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'file=@C:\Users\cb\Desktop\api-data-samples\image\President_Barack_Obama.jpg' \
  -F apiKey=a40c3fc2-585f-4bd0-90be-a95db46be026

Return

630742af-e826-4465-88a2-dd61a7388409

POST /cox/image/processUploadedFileAsync

Description

Returns how much of the scene is included in the picture.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
file byte[] Multipart request property data containing image that should be processed.

Response

Parameter Type Description
requestId string Unique request ID.

Poll Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/image/630742af-e826-4465-88a2-dd61a7388409 \
  -H 'content-type: application/json'

Return

[
    {
        "providers": [
            "aiconix"
        ],
        "requestId": "3dc6bea0-ebf3-46b4-b2c1-8bce9479830b",
        "mediaType": "Image",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "shotSizeResult": {
            "status": "Success",
            "shotSize": "Halbtotale"
        }
    }
]

Poll Request

Request is made using requestId returned by aiconix when image processing was initiated.

Poll Response

Parameter Type Description
providers string[] Name of provider e.g. "Aiconix".
requestId string Unique request ID.
mediaType string Type of media sent to the provider e.g. Image.
operationMode string Operation mode selected in the API configuration. Can be "RawOverallResult", "BudgetResult" or "BestResults".
processingFinished bool Flag if processing is finished True or False.

Shot Size Result

Parameter Type Description
status string Initiated when the request has been sent to the provider. Success when the result is available. More information to Status Codes is provided here.
featureError string Description of failure during processing.
shotSize string Shot size recognized in the image. Possible values: Supertotale, Totale, Halbtotale, Halbnahe, Nahe, Grossaufnahme, Unknown.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Vehicle Detection

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/image/processUploadedFileAsync \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'file=@C:\Users\cb\Desktop\api-data-samples\image\President_Barack_Obama.jpg' \
  -F apiKey=a40c3fc2-585f-4bd0-90be-a95db46be026

Return

630742af-e826-4465-88a2-dd61a7388409

POST /cox/image/processUploadedFileAsync

Description

Returns detected vehicles within an image.

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
file byte[] Multipart request property data containing image that should be processed.

Response

Parameter Type Description
requestId string Unique request ID.

Poll Request

curl -X GET \
  https://api.aiconix.cloud/v1/cox/image/630742af-e826-4465-88a2-dd61a7388409 \
  -H 'content-type: application/json'

Return

[
    {
        "providers": [
            "Deep Vision"
        ],
        "requestId": "4ce68068-74d5-4b6e-88fc-1505798792a0",
        "mediaType": "Image",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "vehiclesResult": {
            "status": "Success",
            "vehicles": [
                {
                    "brand": "Dodge",
                    "model": "Viper",
                    "year": "2008-2009",
                    "confidence": 0.6,
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 0.02847222238779068,
                                "y": 0.3382716178894043
                            },
                            {
                                "x": 0.02847222238779068,
                                "y": 0.934567928314209
                            },
                            {
                                "x": 0.9638888835906982,
                                "y": 0.3382716178894043
                            },
                            {
                                "x": 0.9638888835906982,
                                "y": 0.934567928314209
                            }
                        ]
                    },
                    "view": {
                        "viewType": "Front Left View",
                        "confidence": 1.0
                    }
                }
            ]
        }
    }
]

Poll Request

Request is made using requestId returned by aiconix when image processing was initiated.

Poll Response

Parameter Type Description
providers string[] Name of provider e.g. "Aiconix".
requestId string Unique request ID.
mediaType string Type of media sent to the provider e.g. Image.
operationMode string Operation mode selected in the API configuration. Can be "RawOverallResult", "BudgetResult" or "BestResults".
processingFinished bool Flag if processing is finished True or False.

Vehicle Detection Result

Parameter Type Description
status string Initiated when the request has been sent to the provider. Success when the result is available. More information to Status Codes is provided here.
featureError string Description of failure during processing.
vehicles Object[] List of found vehicles.
brand string Name of detected vehicle brand.
model string Name of detected vehicle model.
year string Detected vehicle year range.
confidence number($double) Confidence value of vehicle determination.
boundingPoly Object[] List of vertices for the four corners of the polygon.
vertices object[] Contains x and y coordinates of polygon corners.
x number($double) X coordinate of the vertices [0-1].
y number($double) Y coordinate of the vertices [0-1].
view object View information about detected vehicle.
viewType string Type of view for detected vehicle.
confidence string Confidence for detected view type.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Synchronous processing

Our API is also supporting synchronous image processing. Creation of API key is same as for asynchronous processing and same API keys can be used for both synchronous and asynchronous processing.

1. Generate an API key

Before we can process a file we need to configure an api key. Please go to config.aiconix.cloud and configure yourself a key for an image media type. Copy the key from the page since we need it in the next step.

Slate guide image

2. Initiate processing of file

Now we can initiate the processing of a file. We simply need to pass the currently configured apiKey and an image file.

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/image \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'file=@C:\Users\cb\Desktop\api-data-samples\image\President_Barack_Obama.jpg' \
  -F apiKey=a40c3fc2-585f-4bd0-90be-a95db46be026

Response

[
    {
        "providers": [
            "Amazon"
        ],
        "requestId": "0d9531cd-91ae-4a67-b910-dcefcb8dfadb",
        "mediaType": "Image",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "labelResult": {
            "status": "Success",
             "labels": [
                 {
                   "description": "Haare",
                     "confidence": 0.9919353723526001
                 },
                 {
                     "description": "Gesicht",
                     "confidence": 0.9908072352409363
                 }...

    }
]

Response

Parameter Type Description
providers string[] Name of provider e.g. "Aiconix".
requestId string Unique request ID.
mediaType string Type of media sent to the provider e.g. Image.
operationMode string Operation mode selected in the API configuration. Can be "RawOverallResult", "BudgetResult" or "BestResults".
processingFinished bool Flag if processing is finished True or False.

Processing from URL Async

Our API is also supporting asynchronous image processing from URL. This processing is same as asynchronous processing from file, only difference is that instead of sending whole file, user can send only URL to file that needs to be processed. Creation of API key is same as for asynchronous processing and same API keys can be used for both synchronous and asynchronous processing.

1. Generate an API key

Before we can process a file we need to configure an api key. Please go to config.aiconix.cloud and configure yourself a key for an image media type. Copy the key from the page since we need it in the next step.

Slate guide image

2. Initiate processing of file

Instead of sending file, url to the file can be provided and aingine will download file and start processing.

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/image/processFromUrlAsync \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'url=https://images.aiconix.cloud/photos/3861961.jpeg' \
  -F apiKey=a40c3fc2-585f-4bd0-90be-a95db46be026

Response

0d9531cd-91ae-4a67-b910-dcefcb8dfadb

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
url string URL to an image that should be processed.

After sending the request call we receive a process id.

3. Poll for request

With the before received processID we can poll for results.

Request

curl GET https://api.aiconix.cloud/v1/cox/image/0d9531cd-91ae-4a67-b910-dcefcb8dfadb

Response

[
    {
        "providers": [
            "Amazon"
        ],
        "requestId": "0d9531cd-91ae-4a67-b910-dcefcb8dfadb",
        "mediaType": "Image",
        "operationMode": "RawOverallResult",
        "processingFinished": false,
        "labelResult": {
            "status": "Initiated",
            "featureError": "Result not ready..."
        }
    } ...
]

Poll Response

Parameter Type Description
providers string[] Name of provider e.g. "Aiconix".
requestId string Unique request ID.
mediaType string Type of media sent to the provider e.g. Image.
operationMode string Operation mode selected in the API configuration. Can be "RawOverallResult", "BudgetResult" or "BestResults".
processingFinished bool Flag if processing is finished True or False.

4. Receive result

Request

curl GET https://api.aiconix.cloud/v1/cox/image/0d9531cd-91ae-4a67-b910-dcefcb8dfadb

Response

[
    {
        "providers": [
            "Amazon"
        ],
        "requestId": "0d9531cd-91ae-4a67-b910-dcefcb8dfadb",
        "mediaType": "Image",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "labelResult": {
            "status": "Success",
             "labels": [
                 {
                   "description": "Haare",
                     "confidence": 0.9919353723526001
                 },
                 {
                     "description": "Gesicht",
                     "confidence": 0.9908072352409363
                 }...

    }
]

The processing is complete if all providers return true in their respective processingFinished flags. With the before received processID we can poll for results.

Processing from URL Sync

Our API is also supporting synchronous image processing from URL. This processing is same as synchronous processing from file, only difference is that instead of sending whole file, user can send only URL to file that needs to be processed. Creation of API key is same as for synchronous processing and same API keys can be used for both synchronous and asynchronous processing.

1. Generate an API key

Before we can process a file we need to configure an api key. Please go to config.aiconix.cloud and configure yourself a key for an image media type. Copy the key from the page since we need it in the next step.

Slate guide image

2. Initiate processing of file

Instead of sending file, url to the file can be provided and aingine will download file and start processing.

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/image/processFromUrl \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'url=https://images.aiconix.cloud/photos/3861961.jpeg' \
  -F apiKey=a40c3fc2-585f-4bd0-90be-a95db46be026

Response

[
    {
        "providers": [
            "Amazon"
        ],
        "requestId": "0d9531cd-91ae-4a67-b910-dcefcb8dfadb",
        "mediaType": "Image",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "labelResult": {
            "status": "Success",
             "labels": [
                 {
                   "description": "Haare",
                     "confidence": 0.9919353723526001
                 },
                 {
                     "description": "Gesicht",
                     "confidence": 0.9908072352409363
                 }...

    }
]

Body

Parameter Type Description
apiKey string Your api key from our api key configuration page.
url string URL to an image that should be processed.

Poll Response

Parameter Type Description
providers string[] Name of provider e.g. "Aiconix".
requestId string Unique request ID.
mediaType string Type of media sent to the provider e.g. Image.
operationMode string Operation mode selected in the API configuration. Can be "RawOverallResult", "BudgetResult" or "BestResults".
processingFinished bool Flag if processing is finished True or False.

Limitations

Following limitations apply for Aingine Image API

Limitations for Image media type

Description Values
Supported extensions jpg/jpeg, png, bmp and other Raster formats
Maximum file size 2048 MB
Maximum image resolution 15000 x 15000 pixels

Text

Guide

This guide will step you through the usage of our api in order to perform a classification on a text.

1. Generate an API key

Before we can process a file we need to configure an api key. Please go to config.aiconix.cloud and configure yourself a key for topics and categories, translation or both of them. Copy the key from the page since we need it in the next step.

Slate guide text

2. Initiate processing of text

Now we simply need to pass the currently configured apiKey and and the text.

curl -X POST \
  https://api.aiconix.cloud/v1/cox/text \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey": "45701f8b-775b-4262-9a29-d9fdfdbd3c18",
    "content": "All along the watchtower. Only the blind can see the vulnerabilities of a broken mind."
}'

3. Receive result

After sending the request call we receive result immediatly.

[
    {
        "providers": [
            "Semantic Engine"
        ],
        "requestId": "bd67283c-a541-4577-902b-faaa80b5f4c4",
        "mediaType": "Text",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "classificationResult": {
            "status": "Success",
            "categories": [
                {
                    "description": "All Along The Watchtower",
                    "confidence": 0.699999988079071
                },
                ...
                {
                    "description": "Cinema, Literature and Audiovisual Media",
                    "confidence": 0.07000000029802322
                },
                {
                    "description": "Electronic Media",
                    "confidence": 0.05999999865889549
                }
            ]
        }
    }
]

Topics and Categories

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/text \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey": "45701f8b-775b-4262-9a29-d9fdfdbd3c18",
    "content": "I was in my car on my way to a new job in Seattle. I put the gas in, put the key in, and then I let it run. I just imagined what the day would be like. A hundred years from now. In 2045, I was a teacher in some school in a poor part of rural China. I started with Chinese history and history of science."
}'

Return

[
    {
        "providers": [
            "Semantic Engine"
        ],
        "requestId": "c108904e-fa8e-4dad-a782-839b772d3357",
        "mediaType": "Text",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "topicResult": {
            "status": "Success",
            "topics": [
                {
                    "description": "City",
                    "confidence": 0.34,
                    "categories": [
                        {
                            "description": "Society"
                        },
                        {
                            "description": "Life"
                        },
                        {
                            "description": "Habitation"
                        }
                    ]
                },
                {
                    "description": "Future",
                    "confidence": 0.33,
                    "categories": [
                        {
                            "description": "Society"
                        },
                        {
                            "description": "Life"
                        }
                    ]
                },
                {
                    "description": "Economics",
                    "confidence": 0.33,
                    "categories": []
                },
                {
                    "description": "Seattle",
                    "confidence": 1.0,
                    "categories": [
                        {
                            "description": "City"
                        }
                    ]
                },
                {
                    "description": "China",
                    "confidence": 1.0,
                    "categories": [
                        {
                            "description": "Country"
                        }
                    ]
                }
            ]
        }
    }
]

POST /cox/text

Description

Request the API to classify the given text.

Request

Parameter Type Description
apiKey string Api key retrieved from COX.
content string The text to be classified.

Response

Parameter Type Description
providers string[] List of providers.
requestID string Corresponding request ID.
mediaType string Type of media sent to the provider: text.
operationMode string Operation mode selected in the COX API configuration. Can be only "RawOverallResult" for text.
processingFinished bool Flag if processing is finished True or False.

Topics and Categorization Result

Parameter Type Description
status string Initiated when the request has been sent to the provider. Success when the result is available. More information to Status Codes is provided here.
topics object[] List of detected topics with description, confidence and categories.
description string Name of the topic.
confidence number($double) Confidence value of topic.
categories object[] List of categories.
description string Name of the category.
parent string Code of IAB category.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Translation

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/text \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey": "45701f8b-775b-4262-9a29-d9fdfdbd3c18",
    "content": "I was in my car on my way to a new job in Seattle. I put the gas in, put the key in, and then I let it run. I just imagined what the day would be like. A hundred years from now. In 2045, I was a teacher in some school in a poor part of rural China. I started with Chinese history and history of science."
}'

Return

[
    {
        "providers": [
            "DeepL"
        ],
        "requestId": "a7a6f659-a35c-44f8-a1b3-41e539758d7c",
        "mediaType": "Text",
        "operationMode": "RawOverallResult",
        "processingFinished": true,
        "textTranslationResult": {
            "status": "Success",
            "translatedText": {
                "translatedText": "Ich war in meinem Auto auf dem Weg zu einem neuen Job in Seattle. Ich habe das Benzin reingetan, den Schlüssel reingetan und dann ließ ich es laufen. Ich habe mir nur vorgestellt, wie der Tag aussehen würde. In hundert Jahren. Im Jahr 2045 war ich Lehrer an einer Schule in einem armen Teil des ländlichen China. Ich begann mit der chinesischen Geschichte und der Wissenschaftsgeschichte."
            }
        }
    }
]

POST /cox/text

Description

Returns input text translated into desired language.

Request

Parameter Type Description
apiKey string Api key retrieved from COX.
content string The text to be classified.

Response

Parameter Type Description
providers string[] List of providers.
requestID string Corresponding request ID.
mediaType string Type of media sent to the provider: text.
operationMode string Operation mode selected in the COX API configuration. Can be only "RawOverallResult" for text.
processingFinished bool Flag if processing is finished True or False.

Text Translation Result

Parameter Type Description
status string Initiated when the request has been sent to the provider. Success when the result is available. More information to Status Codes is provided here.
translatedtext string Translated text into the target language.

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Subtitle Translation

Request

curl -X POST \
  https://api.aiconix.cloud/v1/cox/text/processSubtitle \
  -H 'Content-Type: multipart/form-data;boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'apiKey=45701f8b-775b-4262-9a29-d9fdfdbd3c18' \
  -F 'file=@C:\Users\cb\Desktop\api-data-samples\text\subtitle_sample_de.srt'

Return

1
00:00:00,300 --> 00:00:02,375
Who's what's these are I think

2 00:00:02,375 --> 00:00:03,870 I know his houses - in the village though.

POST /cox/text/processSubtitle

Description

Returns subtitle file translated into desired language.

Request

Parameter Type Description
apiKey string Api key retrieved from COX.
file form-data The subtitle file to be translated. Supported formats are .srt and .stl.

Response

Response is plain text in Srt or Stl format

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request
500 Internal Server Error

Limitations

Following limitations apply for Aingine Text API

Limitations for Text

Description Values
Supported extensions N/A
Maximum text size 100.000 characters

WebHooks

Guide

This guide will step you through the usage of WebHook functionality which servers as a notification when processing is finished.

1. Enter WebHook url in the API Keys page on Config board.

Before we can aingine can send notification about finished processing, URL on which notification will be sent must be configured. Please go to config.aiconix.cloud and configure yourself a WebHook URL.

Webhook

2. Verify WebHook URL

Request that will be send from aingine to the configured WebHook URL

curl -X POST
   https://WebHookURL
  -H 'Content-Type: application/json'
  -d '{
    "requestId" : "TEST"
}'

Description

After saving WebHook URL, aingine will send POST request on entered URL so that it can be verified.

3. Process media file and receive notification on configured WebHook URL

Request that will be send from aingine when processing is finished

[
    {
      "id" : "c11abe5a-0dd2-4514-a35b-e7a02bc833a1",
      "requestId" : "c11abe5a-0dd2-4514-a35b-e7a02bc833a1",
      "webhookUrl" : "<WebHookURL>",
      "retriesTimes" : [
          [2021,1,19,11,0,30,313962000]
        ]
    }
]

Description

After processing is done, aingine will send notification on the WebHookURL with request Id that has finished processing.