API
Intro
We use RESTful APIs for easy integration of your infrastructure with the Cognitive Mill platform. The REST API is supported over the HTTPS protocol.
The content you include in the request body must be JSON encoded.
In the response body, the API returns data in JSON format.
For convenience, we use Swagger UI where you can find all possible example values for sending API requests.
Authorization
First, You need to authorize to be able to send API requests.
There are two options how to get your authorization token (API key):
- Register via the UI and get your authorization token according to the following instruction:
1. Sign in to the demo account at run.cognitivemill.com.
2. Create your own account as described in the Before you start section.
3. Click your newly created account. You land on the Process List page.
4. Click the name of your account in the top-right corner to open the Account Details page.
5. Copy your authorization token.
6. Authorize at api.cognitivemill.com. - Contact us and request your authorization token directly from our support team and authorize at api.cognitivemill.com.

1. Click Authorize in the top-right corner of the page.
2. Paste the token.
3. Click Authorize.
Note that to process recorded media, you should provide only direct permanent links to the media file you want to analyze saved in any remote storage, not the web page.
So you cannot provide links to social media apps and platforms, such as YouTube, Instagram, TikTok, etc.You can also upload media from your device via the UI.
The system supports files with the following extensions: MP4, M3U8, and TS.
API Reference
Process Management
POST /process
Creates a new process
Request
Element | Description | Type | Notes | |
---|---|---|---|---|
config | Process configuration | configuration data object | Optional for most pipelines | |
additionalProp1 | Process configuration key(s) | string | Required for graphics meta, movie trailer, news summary, and all sports trailer compilation pipelines | |
disabled_modules | Names of modules to disable in the process | array of string | Optional | |
inputs | Link to the video(s) to process | array of string | ||
live_config | Configuration for a live streaming | live configuration data object | Required only for live streamings | |
enable | True if the process is created for a live streaming; otherwise, false | Boolean | ||
meta | Metadata settings | metadata object | Optional | |
end_ms | The end time of the segment to process (in milliseconds) | number | Default value is 0 | |
start_ms | The start time of the segment to process (in milliseconds) | number | Default value is 0 | |
title | Process name | string | Required Cannot be empty | |
type | Process type | string | Required Case sensitive |
Example value:
{
"config": {
"additionalProp1": {}
},
"disabled_modules": [
"string"
],
"inputs": [
"string"
],
"live_config": {
"enable": false
},
"meta": {
"end_ms": 0,
"start_ms": 0
},
"title": "string",
"type": "string"
}
Response
Element | Description | Type | Notes | |
---|---|---|---|---|
id | Process ID | string | ||
title | Process name | string | ||
type | Process type | string | ||
status | Process status | string | Possible statuses are: creating, created, ready for downloading, downloading, downloaded, transcoding, transcoded, reading, read, preparation, ready for processing, processing, processed, completion, completed, failed, removing, copying | |
current_stage | Current stage of process | string | ||
created_at | Process creation date and time | string | Time is GMT | |
account_id | Account ID | string | ||
meta | Metadata | metadata object | ||
live | Current status of live process | object | ||
tags | Process tags | object | Tags can be added using POST /process/{id}/tag endpoint | |
finished_at | Process completion date and time | string | ||
is_life | True if the process is created for a live streaming; otherwise, false | Boolean |
POST /process for skip meta
Creates a skip meta process
Example process:
curl -X 'POST' \
'https://api.cognitivemill.com/api/v1/process' \
-H 'accept: application/json' \
-H 'api-token: 0***********************9' \
-H 'Content-Type: application/json' \
-d '{
"title": "SkipMetaExample",
"type": "skip meta old",
"inputs": [
"https://aihunters-media-files.s3.eu-west-1.amazonaws.com/Demo_Videos-Do_Not_Delete/Skip/Skip_4.mp4"
]
}'
Response body:
{
"id": "a107a36e-e219-49b1-b767-fa214a65d2b6",
"title": "SkipMetaExample",
"type": "skip meta old",
"status": "creating",
"current_stage": "",
"created_at": "2022-07-26T14:07:23.166865Z",
"account_id": "9c49c269-6d13-4834-b8f0-5eefe6f10974",
"meta": {
"live": {}
},
"tags": {},
"finished_at": null,
"is_live": false
}
POST /process for graphics meta
Creates a graphics meta process
Note that a graphics meta process requires the following configuration:
"config": { "mask_id":"string" }
Send us an example of the animated graphics image you need to detect to support@aihunters.com — our team will create a graphics animation descriptor and give you the
mask_id
you need to run the process.For more details, view the description of the CognitiveShapes™ product.
View Live stream video processing to learn how to process a live video.
Example process:
curl -X 'POST' \
'https://api.cognitivemill.com/api/v1/process' \
-H 'accept: application/json' \
-H 'api-token: 0***********************9' \
-H 'Content-Type: application/json' \
-d '{
"config": {
"mask_id": "86559c3b-8cb4-4915-8ac3-b08455a00cb0"
},
"live_config": {
"enable": false
},
"title": "LaligaDetectionExample",
"type": "graphics meta",
"inputs": [
"https://aihunters-media-files.s3.eu-west-1.amazonaws.com/Demo_Videos-Do_Not_Delete/Graphics/BarcaMadrid2018.mp4"
]
}'
Response body:
{
"id": "e957aee3-ab1c-4b8c-a973-62f5370d2b6c",
"title": "LaligaDetectionExample",
"type": "graphics meta",
"status": "creating",
"current_stage": "",
"created_at": "2022-07-27T10:22:02.902039Z",
"account_id": "9c49c269-6d13-4834-b8f0-5eefe6f10974",
"meta": {
"live": {}
},
"tags": {},
"finished_at": null,
"is_live": false
}
POST /process for cast meta
Creates a cast meta process
Example process:
curl -X 'POST' \
'https://api.cognitivemill.com/api/v1/process' \
-H 'accept: application/json' \
-H 'api-token: 0***********************9' \
-H 'Content-Type: application/json' \
-d '{
"title": "CastMetaExample",
"type": "cast meta",
"inputs": [
"https://aihunters-media-files.s3.eu-west-1.amazonaws.com/Demo_Videos-Do_Not_Delete/Cast/Nightwish+-+While+Your+Lips+Are+Still+Red.mp4"
]
}'
Response body:
{
"id": "da600e35-0100-4177-bcfd-52bf0a4c2c29",
"title": "CastMetaExample",
"type": "cast meta",
"status": "creating",
"current_stage": "",
"created_at": "2022-07-27T11:57:34.105394Z",
"account_id": "9c49c269-6d13-4834-b8f0-5eefe6f10974",
"meta": {
"live": {}
},
"tags": {},
"finished_at": null,
"is_live": false
}
POST /process for crop meta
Creates a crop meta process
Example process:
curl -X 'POST' \
'https://api.cognitivemill.com/api/v1/process' \
-H 'accept: application/json' \
-H 'api-token: 0***********************9' \
-H 'Content-Type: application/json' \
-d '{
"title": "CropMetaExample",
"type": "crop meta",
"inputs": [
"https://aihunters-media-files.s3.eu-west-1.amazonaws.com/Demo_Videos-Do_Not_Delete/Crop/Star_Wars_The_Last_Jedi_Trailer.mp4"
]
}'
Response body:
{
"id": "36c617fe-db19-4611-be72-916173d95d58",
"title": "CropMetaExample",
"type": "crop meta",
"status": "creating",
"current_stage": "",
"created_at": "2022-07-27T11:59:38.839603Z",
"account_id": "9c49c269-6d13-4834-b8f0-5eefe6f10974",
"meta": {
"live": {}
},
"tags": {},
"finished_at": null,
"is_live": false
}
POST /process for soccer / basketball / hockey / football meta
Creates a soccer / basketball / hockey / football meta process
Example process for soccer meta:
curl -X 'POST' \
'https://api.cognitivemill.com/api/v1/process' \
-H 'accept: application/json' \
-H 'api-token: 0***********************9' \
-H 'Content-Type: application/json' \
-d '{
"title": "SoccerMetaExample",
"type": "soccer meta",
"inputs": [
"https://aihunters-media-files.s3.eu-west-1.amazonaws.com/Demo_Videos-Do_Not_Delete/Sports/Soccer_Barsa-Madrid_5-0.mp4"
]
}'
Response body:
{
"id": "96d1d455-9e52-42c8-97e6-61401870b489",
"title": "SoccerMetaExample",
"type": "soccer meta",
"status": "creating",
"current_stage": "",
"created_at": "2022-07-27T12:58:02.872877Z",
"account_id": "9c49c269-6d13-4834-b8f0-5eefe6f10974",
"meta": {
"live": {}
},
"tags": {},
"finished_at": null,
"is_live": false
}
For other sports, replace the "soccer meta" type with the corresponding sports type: basketball meta, hockey meta, or football meta (for American football)
POST /process for soccer / basketball / hockey / football trailer compilation
Creates a soccer / basketball / hockey / football trailer compilation process
A trailer compilation process generates trailer JSON files with metadata for further trailer set generation.
Note that a trailer compilation process requires external highlight configurations.
The default configuration for soccer trailer compilation is the following:"config": { "config_operator_highlight": { "highlights": { "window_size": 20, "highlight_len": 150, "goal_distrib": [ 0, 0.45, 0, 0.15, 0.4 ], "save_chronology": true, "use_double_labels": false, "type": "soccer" } }, "config_sport_highlight": { "sport_type": "soccer" }
The default configuration for basketball trailer compilation is the following:
"config": { "config_operator_highlight": { "highlights": { "window_size": 20, "highlight_len": 150, "goal_distrib": [ 0, 0.15, 0.45, 0.25, 0.15, 0 ], "save_chronology": true, "use_double_labels": false, "type": "basketball" } }, "config_sport_highlight": { "sport_type": "basketball" }
The default configuration for hockey trailer compilation is the following:
"config": { "config_operator_highlight": { "highlights": { "window_size": 20, "highlight_len": 150, "goal_distrib": [ 0, 0.45, 0, 0.15, 0.4 ], "save_chronology": true, "use_double_labels": false, "type": "hockey" } }, "config_sport_highlight": { "sport_type": "hockey" }
The default configuration for football trailer compilation is the following:
"config": { "config_operator_highlight": { "highlights": { "window_size": 20, "highlight_len": 150, "goal_distrib": [ 0, 0.45, 0.15, 0.4 ], "save_chronology": true, "use_double_labels": false, "type": "american_football" } }, "config_sport_highlight": { "sport_type": "american_football" }
The trailer compilation process requires segments from the meta JSON file.
Snippet of an example soccer trailer compilation process with only two segments displayed:
curl -X 'POST' \
'https://api.cognitivemill.com/api/v1/process' \
-H 'accept: application/json' \
-H 'api-token: 0***********************9' \
-H 'Content-Type: application/json' \
-d '{
"title": "SoccerTrailerExample",
"type": "soccer trailer compilation",
"inputs": [
"https://aihunters-media-files.s3.eu-west-1.amazonaws.com/Demo_Videos-Do_Not_Delete/Sports/Soccer_Barsa-Madrid_5-0.mp4"
],
"config": {
"config_operator_highlight": {
"highlights": {
"window_size": 20,
"highlight_len": 150,
"goal_distrib": [
0,
0.45,
0,
0.15,
0.4
],
"save_chronology": true,
"use_double_labels": false,
"type": "soccer"
}
},
"config_sport_highlight": {
"sport_type": "soccer"
},
"meta": {
"data":
{
"id": "meta",
"segments":
[
{
"anomaly_score": 1,
"dynamics_score": 0,
"end": {
"ms": 5950,
"time": "0:00:05.950000"
},
"label": "Side content",
"median_area_person": 0.603,
"median_person_quantity_for_frame": 1,
"normalised_dynamics_score": 0,
"repr_ms": 2833.33,
"segments": [
{
"end": {
"ms": 5950,
"time": "0:00:05.950000"
},
"repr_ms": 2833.33,
"start": {
"ms": 0,
"time": "0:00:00"
},
"type": "subshot"
}
],
"start": {
"ms": 0,
"time": "0:00:00"
},
"type": "shot"
},
{
"anomaly_score": 0.7822166199914391,
"dynamics_score": 0.623,
"end": {
"ms": 11516.665,
"time": "0:00:11.516665"
},
"label": "Fan zone",
"median_area_person": 0.03,
"median_person_quantity_for_frame": 3,
"normalised_dynamics_score": 0.1119162011725153,
"repr_ms": 8733.33,
"segments": [
{
"end": {
"ms": 8683.335,
"time": "0:00:08.683335"
},
"repr_ms": 7000,
"start": {
"ms": 5950,
"time": "0:00:05.950000"
},
"type": "subshot"
},
...
Response body:
{
"id": "735aa346-876c-4c61-bccd-d2c1d136345a",
"title": "SoccerTrailerExample",
"type": "soccer trailer compilation",
"status": "creating",
"current_stage": "",
"created_at": "2022-07-28T12:55:20.968035Z",
"account_id": "9c49c269-6d13-4834-b8f0-5eefe6f10974",
"meta": {
"live": {}
},
"tags": {},
"finished_at": null,
"is_live": false
}
POST /process for movie trailer
Creates a movie trailer process
Note that a movie trailer process requires the following trailer length configuration:
"config": { "config_movie_trailer_external": { "trailer": { "length": 60 }
The trailer length should be set in seconds. 60 seconds is the default length that you can customize according to your needs.
Example process:
curl -X 'POST' \
'https://api.cognitivemill.com/api/v1/process' \
-H 'accept: application/json' \
-H 'api-token: 0***********************9' \
-H 'Content-Type: application/json' \
-d '{
"config": {
"config_movie_trailer_external": {
"trailer": {
"length": 60
}
}
},
"title": "MovieTrailerExample",
"type": "movie trailer",
"inputs": [
"https://aihunters-media-files.s3.eu-west-1.amazonaws.com/Demo_Videos-Do_Not_Delete/Movie_trailer/The+Matrix.mp4"
]
}'
Response body:
{
"id": "1d7f3462-2880-43db-aa39-03be5a6137da",
"title": "MovieTrailerExample",
"type": "movie trailer",
"status": "creating",
"current_stage": "",
"created_at": "2022-07-28T14:03:12.191024Z",
"account_id": "9c49c269-6d13-4834-b8f0-5eefe6f10974",
"meta": {
"live": {}
},
"tags": {},
"finished_at": null,
"is_live": false
}
POST /process for news summary
Creates a news summary process
Note that a news summary process requires the following external configuration:
"config":{ "config_preview_external":{ "text": { "classification": { "labels": [ "artifacts", "animals", "food", "sports", "tech", "politics", "business", "entertainment", "love", "history", "war", "music", "religion", "people", "children", "traveling", "medicine", "climate", "crime", "death" ] }, "summarization": { "ratio": null, "min_length": null, "max_length": null, "num_sentences": 5 } }, "visual": { "include_non_informative_content": false, "minimal_threshold": 5 } }, "audio_external_config":{ "mode": "full", "light_mode": { "min_silence_len": 300, "keep_silence": 0 }, "full_mode": { "diarization": false, "speech_to_text": true } }
You can replace the default labels for topic identification with your labels.
Example process:
curl -X 'POST' \
'https://api.cognitivemill.com/api/v1/process' \
-H 'accept: application/json' \
-H 'api-token: 0***********************9' \
-H 'Content-Type: application/json' \
-d '{
"title": "NewsSummaryExample",
"type": "news summary",
"inputs": [
"https://aihunters-media-files.s3.eu-west-1.amazonaws.com/Demo_Videos-Do_Not_Delete/News_Summary/Kayak_Murder_or_Accident.mp4"
],
"config":{
"config_preview_external":{
"text": {
"classification": {
"labels": [
"artifacts",
"animals",
"food",
"sport",
"tech",
"politics",
"business",
"entertainment",
"love",
"history",
"war",
"music",
"religion",
"people",
"children",
"traveling",
"medicine",
"climate",
"crime",
"death"
]
},
"summarization": {
"ratio": null,
"min_length": null,
"max_length": null,
"num_sentences": 5
}
},
"visual": {
"include_non_informative_content": false,
"minimal_threshold": 5
}
},
"audio_external_config":{
"mode": "full",
"light_mode": {
"min_silence_len": 300,
"keep_silence": 0
},
"full_mode": {
"diarization": false,
"speech_to_text": true
}
}}
}'
Response body:
{
"id": "ecb56d5d-765f-4772-abcb-6821eb05b985",
"title": "NewsSummaryExample",
"type": "news summary",
"status": "creating",
"current_stage": "",
"created_at": "2022-07-28T22:21:01.615252Z",
"account_id": "9c49c269-6d13-4834-b8f0-5eefe6f10974",
"meta": {
"live": {}
},
"tags": {},
"finished_at": null,
"is_live": false
}
POST /process for media mill
Creates a media mill process
Note that a media mill process requires the following trailer type configuration:
"config": { "types": [ "string" ], "trailer": { "id": "string", ] }
Trailer type is the same value as the trailer id.
The media mill process requires segments with start and end time (trailer.json) given in milliseconds to generate the output media.
Note that the JSON file contains data
with labeled segments for further processing and metadata
that contains the information about modules and module versions for internal use.
Enter only the data
object to generate a reel.
Example process based on a movie trailer JSON file:
curl -X 'POST' \
'https://api.cognitivemill.com/api/v1/process' \
-H 'accept: application/json' \
-H 'api-token: bc8e590972ba195c5d780d0e953ef0f5' \
-H 'Content-Type: application/json' \
-d '{
"type": "media mill",
"title": "MediaMillExample",
"inputs": [
"https://aihunters-media-files.s3.eu-west-1.amazonaws.com/Demo_Videos-Do_Not_Delete/Movie_trailer/Pirates+Of+The+Caribbean+-+The+Curse+Of+The+Black+Pearl.mp4"
],
"config": {
"types": [
"diversity_trailer"
],
"trailer": {
"id": "diversity_trailer",
"segments": [
{
"end": {
"ms": 820892
},
"start": {
"ms": 816680
}
},
{
"end": {
"ms": 1126083
},
"start": {
"ms": 1121040
}
},
{
"end": {
"ms": 1658346
},
"start": {
"ms": 1655148
}
},
{
"end": {
"ms": 7687630
},
"start": {
"ms": 7682600
}
}
]
}
}
}'
Response body:
{
"id": "e6f860cc-db75-4e16-a56f-892ca5f8d462",
"title": "MediaMillExample",
"type": "media mill",
"status": "creating",
"current_stage": "",
"created_at": "2022-07-29T07:56:25.07089Z",
"account_id": "9c49c269-6d13-4834-b8f0-5eefe6f10974",
"meta": {
"live": {}
},
"tags": {},
"finished_at": null,
"is_live": false
}
Example process based on a news summary JSON file:
curl -X 'POST' \
'https://api.cognitivemill.com/api/v1/process' \
-H 'accept: application/json' \
-H 'api-token: b******************************5' \
-H 'Content-Type: application/json' \
-d '{
"type": "media mill",
"title": "News_summary_preview",
"inputs": [
"https://aihunters-media-files.s3.eu-west-1.amazonaws.com/Demo_Videos-Do_Not_Delete/News_Summary/News_Leftover_Stadiums-NBC_News.mp4"
],
"config": {
"types": [
"visual preview_1"
],
"trailer": [
{
"id": "visual preview_1",
"segments": [
{
"end": {
"ms": 19318.46,
"time": "0:00:19.318460"
},
"repr_ms": 17284.09,
"start": {
"ms": 17318.46,
"time": "0:00:17.318460"
}
},
{
"end": {
"ms": 58075.2,
"time": "0:00:58.075200"
},
"repr_ms": 55589.36,
"start": {
"ms": 56075.2,
"time": "0:00:56.075200"
}
},
{
"end": {
"ms": 67115.63,
"time": "0:01:07.115630"
},
"repr_ms": 66700.56,
"start": {
"ms": 65115.63,
"time": "0:01:05.115630"
}
},
{
"end": {
"ms": 104553.36499999999,
"time": "0:01:44.553365"
},
"repr_ms": 105639.81,
"start": {
"ms": 102553.36499999999,
"time": "0:01:42.553365"
}
},
{
"end": {
"ms": 128728.74,
"time": "0:02:08.728740"
},
"repr_ms": 128796.48,
"start": {
"ms": 126728.74,
"time": "0:02:06.728740"
}
},
{
"end": {
"ms": 154888.44,
"time": "0:02:34.888440"
},
"repr_ms": 144712.52,
"start": {
"ms": 152888.44,
"time": "0:02:32.888440"
}
},
{
"end": {
"ms": 165650.29499999998,
"time": "0:02:45.650295"
},
"repr_ms": 164132.1,
"start": {
"ms": 163650.29499999998,
"time": "0:02:43.650295"
}
},
{
"end": {
"ms": 184952.07,
"time": "0:03:04.952070"
},
"repr_ms": 186721.53,
"start": {
"ms": 182952.07,
"time": "0:03:02.952070"
}
}
],
"type": "time segments"
}
]
}
}'
Response body:
{
"id": "39c325db-3765-40ce-8b3f-7abd94969b1a",
"title": "News_summary_preview",
"type": "media mill",
"status": "creating",
"current_stage": "",
"created_at": "2022-08-16T14:55:55.532278Z",
"account_id": "9c49c269-6d13-4834-b8f0-5eefe6f10974",
"meta": {
"live": {}
},
"tags": {},
"finished_at": null,
"is_live": false
}
POST /process for nude meta
Creates a nude meta process
Example process:
curl -X 'POST' \
'https://api.cognitivemill.com/api/v1/process' \
-H 'accept: application/json' \
-H 'api-token: 0***********************9' \
-H 'Content-Type: application/json' \
-d '{
"inputs": [
"https://aihunters-media-files.s3.eu-west-1.amazonaws.com/Demo_Videos-Do_Not_Delete/Nude/002.mp4"
],
"title": "NudeMetaExample",
"type": "nude meta"
}
'
Response body:
{
"id": "e5bc8a56-1a5d-42cd-bb86-4e128125cb50",
"title": "NudeMetaExample",
"type": "nude meta",
"status": "creating",
"current_stage": "",
"created_at": "2022-08-23T15:53:25.361422Z",
"account_id": "9c49c269-6d13-4834-b8f0-5eefe6f10974",
"meta": {
"live": {}
},
"tags": {},
"finished_at": null,
"is_live": false
}
GET /process
Returns data about processes by filters
Request
Element | Description | Type | Notes |
---|---|---|---|
type | Type of process to filter by | string | Optional Case sensitive |
offset | Process number to start filtering from | integer | Optional |
limit | Number of processes to return | integer | Optional |
tags | Process tag(s) to filter by | string | Optional Tags’ format: key=value;key2=value2;key3.subkey=value3 |
statuses | Process status(es) to filter by | string | Optional Separate multiple statuses with a semicolon Possible statuses are: creating, created, ready for downloading, downloading, downloaded, transcoding, transcoded, reading, read, preparation, ready for processing, processing, processed, completion, completed, failed, removing, and copying |
Example process:
Where "type": "movie trailer"
curl -X 'GET' \
'https://api.cognitivemill.com/api/v1/process?type=movie%20trailer' \
-H 'accept: application/json' \
-H 'api-token: 0***********************9'
Response
Element | Description | Type | Notes | |||
---|---|---|---|---|---|---|
pagination | Returned processes list data | object | ||||
limit | Number of processes to return | integer | ||||
offset | Process number to start filtering from | integer | ||||
total | Total number of processes meeting filtering criteria | integer | ||||
processes | List of returned processes | array of objects | ||||
id | Process ID | string | ||||
title | Process name | string | ||||
type | Process type | string | ||||
status | Process status | string | Possible statuses are: creating, created, ready for downloading, downloading, downloaded, transcoding, transcoded, reading, read, preparation, ready for processing, processing, processed, completion, completed, failed, removing, and copying | |||
current_stage | Current stage of process | string | ||||
created_at | Process creation time | string | Time is GMT | |||
account_id | Account ID | string | ||||
meta | Metadata | metadata object | ||||
results | Process output | array of object | ||||
name | Result name | string | Valid names: contents meta trailer shots | |||
type | Output type | string | Valid types: json, media | |||
live | Current status of live process | object | ||||
tags | Process tags | object | ||||
finished_at | Process completion date and time | string | ||||
is_life | True if the process is created for a live streaming; otherwise, false | Boolean |
Response body:
{
"pagination": {
"limit": 0,
"offset": 0,
"total": 8
},
"processes": [
{
"id": "e7a44f20-aa33-4884-8d85-89ea7954c5c6",
"title": "MovieTrailer_Example",
"type": "movie trailer",
"status": "completed",
"current_stage": "stage-4",
"created_at": "2022-07-28T14:42:03.184886Z",
"account_id": "9c49c269-6d13-4834-b8f0-5eefe6f10974",
"meta": {
"results": [
{
"name": "contents",
"type": "json"
},
{
"name": "meta",
"type": "json"
},
{
"name": "trailer",
"type": "json"
},
{
"name": "shots",
"type": "json"
}
],
"live": {}
},
"tags": {},
"finished_at": "2022-07-28T15:15:25.408433Z",
"is_live": false
},
...
GET /process/{id}
Returns data about the processes by process ID
Request
Element | Description | Type | Notes |
---|---|---|---|
id | Process ID | string | Required |
Example process:
curl -X 'GET' \
'https://api.cognitivemill.com/api/v1/process/32401bb9-a296-4960-95db-906a61ccf623' \
-H 'accept: application/json' \
-H 'api-token: 0***********************9'
Response
Element | Description | Type | Notes | |||
---|---|---|---|---|---|---|
pagination | Returned processes list data | object | ||||
limit | Number of processes to return | integer | ||||
offset | Process number to start filtering from | integer | ||||
total | Total number of processes meeting filtering criteria | integer | ||||
processes | List of returned processes | array of objects | ||||
id | Process ID | string | ||||
title | Process name | string | ||||
type | Process type | string | ||||
status | Process status | string | Possible statuses are: creating, created, ready for downloading, downloading, downloaded, transcoding, transcoded, reading, read, preparation, ready for processing, processing, processed, completion, completed, failed, removing, and copying | |||
current_stage | Current stage of process | string | ||||
created_at | Process creation time | string | Time is GMT | |||
account_id | Account ID | string | ||||
meta | Metadata | metadata object | ||||
results | Process output | array of object | ||||
name | Result name | string | Valid names: contents meta trailer shots | |||
type | Output type | string | Valid types: json, media | |||
live | Current status of live process | object | ||||
tags | Process tags | object | ||||
finished_at | Process completion date and time | string | ||||
is_life | True if the process is created for a live streaming; otherwise, false | Boolean |
PUT /process/ {id}
Edits the process title
Request
Element | Description | Type | Notes | |
---|---|---|---|---|
id | Process ID | string | Required | |
processForm | Edit process form | object | Required | |
title | Process name to edit | string | Required |
Example process:
curl -X 'PUT' \
'https://api.cognitivemill.com/api/v1/process/e7a44f20-aa33-4884-8d85-89ea7954c5c6' \
-H 'accept: application/json' \
-H 'api-token: b*****************************5' \
-H 'Content-Type: application/json' \
-d '{
"title": "New_Process_Name"
}'
Response
Element | Description | Type | Notes | |||
---|---|---|---|---|---|---|
pagination | Returned processes list data | object | ||||
limit | Number of processes to return | integer | ||||
offset | Process number to start filtering from | integer | ||||
total | Total number of processes meeting filtering criteria | integer | ||||
processes | List of returned processes | array of objects | ||||
id | Process ID | string | ||||
title | Process name | string | ||||
type | Process type | string | ||||
status | Process status | string | Possible statuses are: creating, created, ready for downloading, downloading, downloaded, transcoding, transcoded, reading, read, preparation, ready for processing, processing, processed, completion, completed, failed, removing, and copying | |||
current_stage | Current stage of process | string | ||||
created_at | Process creation time | string | Time is GMT | |||
account_id | Account ID | string | ||||
meta | Metadata | metadata object | ||||
results | Process output | array of object | ||||
name | Result name | string | Valid names: contents meta trailer shots | |||
type | Output type | string | Valid types: json, media | |||
live | Current status of live process | object | ||||
tags | Process tags | object | ||||
finished_at | Process completion date and time | string | ||||
is_life | True if the process is created for a live streaming; otherwise, false | Boolean |
Response body:
{
"id": "e7a44f20-aa33-4884-8d85-89ea7954c5c6",
"title": "New_Process_Name",
"type": "movie trailer",
"status": "completed",
"current_stage": "stage-4",
"created_at": "2022-07-28T14:42:03.184886Z",
"account_id": "9c49c269-6d13-4834-b8f0-5eefe6f10974",
"meta": {
"results": [
{
"name": "contents",
"type": "json"
},
{
"name": "meta",
"type": "json"
},
{
"name": "trailer",
"type": "json"
},
{
"name": "shots",
"type": "json"
}
],
"live": {}
},
"tags": {},
"finished_at": "2022-07-28T15:15:25.408433Z",
"is_live": false
}
DELETE /process/{id}
Deletes a process by process ID
Request
Element | Description | Type | Notes |
---|---|---|---|
id | Process ID | string | Required |
Example process:
curl -X 'DELETE' \
'https://api.cognitivemill.com/api/v1/process/e6f860cc-db75-4e16-a56f-892ca5f8d462' \
-H 'accept: application/json' \
-H 'api-token: b*****************************5'
Response body:
"success"
GET /process/ {id}/ errors
Returns an error message for a failed process by process ID
Request
Element | Description | Type | Notes |
---|---|---|---|
id | Process ID | string | Required |
Example process:
curl -X 'GET' \
'https://api.cognitivemill.com/api/v1/process/a469c49e-b24e-4e78-9e7f-4432cbdb19ca/errors' \
-H 'accept: application/json' \
-H 'api-token: 0***********************9'
Response body:
Contains an error message
"1 | 28 Jul 22 13:39 +0000 | optionutil config_movie_trailer_external is required\r\n"
GET /process/ {id}/ inputs
Returns URL for live and recorded videos by process ID
Note that first you must create a process with the configuration for live streams enabled, for example, graphics meta:
"live_config": { "enable": true }
After the process is created, take the process ID and use
GET /process/ {id}/ inputs
to get the URL for your live streaming.
Request
Element | Description | Type | Notes |
---|---|---|---|
id | Process ID | string | Required |
Example process:
curl -X 'GET' \
'https://api.cognitivemill.com/api/v1/process/817ef9ce-587a-475c-83ee-f06c66d59c71/inputs' \
-H 'accept: application/json' \
-H 'api-token: 0***********************9'
Response
Element | Description | Type | Notes |
---|---|---|---|
id | Input ID | string | |
url | Returned channel URL for live streaming | string | |
created_at | Process creation time | string | Time is GMT |
process_id | Process ID | string | |
index | Numerical order of inputs | integer |
Response body:
[
{
"id": "3e33d741-7478-4d3c-b217-586522132d76",
"url": "srt://live.cognitivemill.com:1935?streamid=input/live/817ef9ce-587a-475c-83ee-f06c66d59c71,token=bc8e590972ba195c5d780d0e953ef0f5",
"created_at": "2022-08-01T09:04:34.176857Z",
"process_id": "817ef9ce-587a-475c-83ee-f06c66d59c71",
"index": 0
}
]
GET /process/ {id}/ progress
Returns the process status by process ID
Request
Element | Description | Type | Notes |
---|---|---|---|
id | Process ID | string | Required |
Example process:
curl -X 'GET' \
'https://api.cognitivemill.com/api/v1/process/97a2f1f6-5b3d-430c-98f7-d23adf837c44/progress' \
-H 'accept: application/json' \
-H 'api-token: 0***********************9'
Response
Element | Description | Type | Notes | |
---|---|---|---|---|
progress | Processing progress 0 to 1 for the whole process | number | ||
percent | Processing progress in % for the whole process | string | ||
features | Object of modules used in the process | object | ||
type | Module name with processing progress data for each module | object | ||
value | Processing progress 0 to 1 for the specified module | number | ||
percent | Processing progress in % for the specified module | string | ||
Index | Numerical order of the module | integer |
Response body:
{
"progress": 0.17391305,
"percent": "17.39",
"features": [
{
"type": "DOWNLOAD",
"value": 0,
"percent": "0.00",
"index": 1
},
{
"type": "PREPARE_DATA",
"value": 1,
"percent": "100.00",
"index": 2
},
{
"type": "QUOTA",
"value": 1,
"percent": "100.00",
"index": 3
},
{
"type": "VALIDATION",
"value": 1,
"percent": "100.00",
"index": 4
},
{
"type": "PREPARE_TRANSCODING",
"value": 0,
"percent": "0.00",
"index": 8
},
{
"type": "TRANSCODING",
"value": 0,
"percent": "0.00",
"index": 9
},
{
"type": "TRANSCODING_MERGER",
"value": 0,
"percent": "0.00",
"index": 10
},
{
"type": "VIDEO_SPLITTER",
"value": 0,
"percent": "0.00",
"index": 11
},
{
"type": "CONTENT_WRITER",
"value": 0.25,
"percent": "25.00",
"index": 13
},
{
"type": "READ_VIDEO_META",
"value": 0,
"percent": "0.00",
"index": 15
},
{
"type": "CONTENT_PUBLISHER",
"value": 0,
"percent": "0.00",
"index": 17
},
{
"type": "CROP_META",
"value": 0,
"percent": "0.00",
"index": 18
},
{
"type": "MOTION_STREAMLINES",
"value": 0,
"percent": "0.00",
"index": 19
},
{
"type": "PREPARER",
"value": 0,
"percent": "0.00",
"index": 20
},
{
"type": "SPATIAL_SALIENCY",
"value": 0,
"percent": "0.00",
"index": 21
},
{
"type": "VIDEOSHOT_SPLITTER",
"value": 0,
"percent": "0.00",
"index": 22
},
{
"type": "VISUAL_REPR",
"value": 0,
"percent": "0.00",
"index": 23
},
{
"type": "SAVER",
"value": 0,
"percent": "0.00",
"index": 25
}
]
}
GET /process/{id}/result
Returns one process result by process ID and result name
Request
Example for a metadata process:
curl -X 'GET' \
'https://api.cognitivemill.com/api/v1/process/f4e1e81b-a6ad-491a-af37-f1f74c4ce5cd/result?type=result' \
-H 'accept: application/json' \
-H 'api-token: 0***********************9'
In the response body, you get a JSON file with metadata for the processed video.
Here's a snippet of a meta JSON file for a skip meta process:
Response body
{
"data": [
{
"events": [
{
"ms": 527600,
"time": "0:08:47.600000",
"type": "closing credits"
},
{
"ms": 527600,
"time": "0:08:47.600000",
"type": "safe point"
}
],
"id": "credits events",
"type": "time events"
},
{
"id": "credits segments",
"segments": [
{
"end": {
"ms": 898880,
"time": "0:14:58.880000"
},
"start": {
"ms": 527600,
"time": "0:08:47.600000"
},
"type": "closing credits"
}
],
"type": "time segments"
}
],
...
For more information about the metadata included in the meta.json file, view cognitivemill.com > the product of interest > Output Metadata.
Example for a media generation process:
curl -X 'GET' \
'https://api.cognitivemill.com/api/v1/process/938433c9-a8b3-439e-b249-469f200770f3/result?type=diversity_trailer' \
-H 'accept: application/json' \
-H 'api-token: 0***********************9'
In the response body, you get a URL for the generated output media.
Response body
{
"url": "https://platform-db-results.s3.eu-west-1.amazonaws.com/ee57fbad-10dd-42b6-b38a-28868a2a5a1d/diversity_trailer.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAUKULPX4OLQH7KWKM%2F20220307%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220307T111329Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=715bddfdfbed49bab3b818236a0394c2d2b1986f7b479034c7232ccf38e2a911"
}
POST /process/{id}/tag
Adds tags to a process
Request
Element | Description | Type | Notes | ||
---|---|---|---|---|---|
id | Process ID | string | Required | ||
user | Form for adding tags | object | Required | ||
tags | Key-value pairs for tagging a process | array of string | Required key=value tag can be used for filtering in GET /process | ||
key | Tag key | string | Required Valid values: letters, numbers, and underscores | ||
value | Tag value | string, number, object | Required Valid values: letters, numbers, and underscores |
Example process:
curl -X 'POST' \
'https://api.cognitivemill.com/api/v1/process/ebed4091-4ff2-459b-8411-4098f9be5cfb/tag' \
-H 'accept: application/json' \
-H 'api-token: b************************5' \
-H 'Content-Type: application/json' \
-d '{
"tags": [
{
"key": "mill",
"value": "01"
}
]
}'
Response
Element | Description | Type | Notes | |||
---|---|---|---|---|---|---|
pagination | Returned processes list data | object | ||||
limit | Number of processes to return | integer | ||||
offset | Process number to start filtering from | integer | ||||
total | Total number of processes meeting filtering criteria | integer | ||||
processes | List of returned processes | array of objects | ||||
id | Process ID | string | ||||
title | Process name | string | ||||
type | Process type | string | ||||
status | Process status | string | Possible statuses are: creating, created, ready for downloading, downloading, downloaded, transcoding, transcoded, reading, read, preparation, ready for processing, processing, processed, completion, completed, failed, removing, and copying | |||
current_stage | Current stage of process | string | ||||
created_at | Process creation time | string | Time is GMT | |||
account_id | Account ID | string | ||||
meta | Metadata | metadata object | ||||
results | Process output | array of object | ||||
name | Result name | string | Valid names: contents meta trailer shots | |||
type | Output type | string | Valid types: json, media | |||
live | Current status of live process | object | ||||
tags | Process tags | object | ||||
finished_at | Process completion date and time | string | ||||
is_life | True if the process is created for a live streaming; otherwise, false | Boolean |
Response body:
{
"id": "ebed4091-4ff2-459b-8411-4098f9be5cfb",
"title": "MediaMillExample",
"type": "media mill",
"status": "completed",
"current_stage": "stage-3",
"created_at": "2022-07-29T08:01:18.351604Z",
"account_id": "9c49c269-6d13-4834-b8f0-5eefe6f10974",
"meta": {
"results": [
{
"name": "diversity_trailer",
"type": "media"
}
],
"live": {}
},
"tags": {
"mill": "01"
},
"finished_at": "2022-07-29T08:07:52.236999Z",
"is_live": false
}
DELETE /process/{id}/tag
Removes tags from a process
Request
Element | Description | Type | Notes | |
---|---|---|---|---|
id | Process ID | string | Required | |
user | Form for deleting tags | object | Required | |
keys | Keys of the tags to delete | array of string | Required |
Example process:
curl -X 'DELETE' \
'https://api.cognitivemill.com/api/v1/process/ebed4091-4ff2-459b-8411-4098f9be5cfb/tag' \
-H 'accept: application/json' \
-H 'api-token: b*************************5' \
-H 'Content-Type: application/json' \
-d '{
"keys": [
"mill"
]
}'
Response body:
{
"id": "ebed4091-4ff2-459b-8411-4098f9be5cfb",
"title": "MediaMillExample",
"type": "media mill",
"status": "completed",
"current_stage": "stage-3",
"created_at": "2022-07-29T08:01:18.351604Z",
"account_id": "9c49c269-6d13-4834-b8f0-5eefe6f10974",
"meta": {
"results": [
{
"name": "diversity_trailer",
"type": "media"
}
],
"live": {}
},
"tags": {},
"finished_at": "2022-07-29T08:07:52.236999Z",
"is_live": false
}
The API returns the complete data on the process with the tag deleted as shown in the response body above.
HTTP response status codes
200 OK
The request was completed successfully.
Error responses:
400 Bad Request
The client request cannot be processed by the server due to malformed request syntax, invalid request message framing, deceptive request routing, etc.
401 Unauthorized
The server will not complete the client request unless you provide a valid authentication token.
403 Forbidden
The client request cannot be processed due to lack of rights to video resources. An incorrect URL to the video may cause this error too.
404 Page Not Found
The client request is sent to the endpoint that does not exist.
500 Internal Server Error
The server encountered an unexpected condition that prevented it from fulfilling the request.
502 Bad Gateway
A server communication error that appears when the server acting as a gateway or proxy gets an invalid response from another server.
Gateway Timeout Error
The server acting as a gateway cannot get a needed response from the upstream server in time.
Live stream video processing
Cognitive Mill supports live stream video processing.
We use Secure Reliable Transport (SRT) open-source streaming protocol that provides high-quality, secure, and low-latency live streaming. It’s content-agnostic and supports all video and audio codecs as well as transport and package formats.
It is relatively new and may require a compatibility check to make sure that your streaming hardware and software support the SRT protocol.
How to run a live stream video processing
Before running a live-stream process, you need to get authorized at api.cognitivemill.com.
When you get authorized, you need to do the following:
1. Create a POST /process
request for the required type of process.
Note: you have two minutes to complete the following steps and start streaming. Two minutes is the default time the process will be waiting for the stream to start; otherwise, it fails.
Contact us if you need to change this timeout.
Below is an example of a POST /process
request for a graphics meta process.
Before clicking the Execute button, make sure you’ve done the following:
- Got the
mask_id
for the configuration:"config": { "mask_id": "string"" }
Send us an example of the animated graphics image you need to detect to support@aihunters.com — our team will create a graphics animation descriptor and give you themask_id
you need to run the process.- Set the following live configuration:
"live_config": { "enable": true }
Example process:
curl -X 'POST' \
'https://api.cognitivemill.com/api/v1/process' \
-H 'accept: application/json' \
-H 'api-token: 0***********************9' \
-H 'Content-Type: application/json' \
-d '{
"config": {
"mask_id": "86559c3b-8cb4-4915-8ac3-b08455a00cb0"
},
"live_config": {
"enable": true
},
"title": "LaligaDetectionExample",
"type": "graphics meta",
"inputs": [
]
}'
In the response body, you get the process id
. Copy it to run the next process.
Response body:
{
"id": "e957aee3-ab1c-4b8c-a973-62f5370d2b6c",
"title": "LaligaDetectionExample",
"type": "graphics meta",
"status": "creating",
"current_stage": "",
"created_at": "2022-07-27T10:22:02.902039Z",
"account_id": "9c49c269-6d13-4834-b8f0-5eefe6f10974",
"meta": {
"live": {}
},
"tags": {},
"finished_at": null,
"is_live": true
}
2. Use the GET /process / {id} / inputs
endpoint with the copied id
.
curl -X 'POST' \
'https://api.cognitivemill.com/api/v1/process/4f6768fc-669d-48e0-a6e6-f490bc5151a4/inputs' \
-H 'accept: application/json' \
-H 'api-token: 0***********************9'
In the response body, you get the required SRT ingestion URL for your live stream.
Response body:
[
{
"id": "74311771-e05d-41ec-a3d2-c875cdd0a531",
"url": "srt://live.cognitivemill.com:1935?streamid=input/live/4f6768fc-669d-48e0-a6e6-f490bc5151a4,token=bc8e590972ba195c5d780d0e953ef0f5",
"created_at": "2022-07-20T21:04:30.297868Z",
"process_id": "4f6768fc-669d-48e0-a6e6-f490bc5151a4",
"index": 0
}
]
3. When the status of the process you started at step 1 changes to Processing, start the live stream to the provided URL.
The processing of the live video starts.
Mind that if the stream breaks, you will have two minutes to resume it before the process fails without a chance to recover. Two minutes is the default timeout set in the internal configuration. Contact us to expand it if needed.