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
`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

Element	Description	Type	Notes
`type`	Result name	string	Though the element is called “type”, you need to enter the result “name”. Use `GET /process` request to get the result name. Note that the “type” field is case sensitive.
`id`	Process ID	string	Required

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 the mask_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.

API

Intro

Authorization

API Reference

POST /process

POST /process for skip meta

POST /process for graphics meta

POST /process for cast meta

POST /process for crop meta

POST /process for soccer / basketball / hockey / football meta

POST /process for soccer / basketball / hockey / football trailer compilation

POST /process for movie trailer

POST /process for news summary

POST /process for media mill

POST /process for nude meta

GET /process

GET /process/{id}

PUT /process/ {id}

DELETE /process/{id}

GET /process/ {id}/ errors

GET /process/ {id}/ inputs

GET /process/ {id}/ progress

GET /process/{id}/result

POST /process/{id}/tag

DELETE /process/{id}/tag

HTTP response status codes

Live stream video processing

Contact Support

`POST /process`

`POST /process for skip meta`

`POST /process for graphics meta`

`POST /process for cast meta`

`POST /process for crop meta`

`POST /process for soccer / basketball / hockey / football meta`

`POST /process for soccer / basketball / hockey / football trailer compilation`

`POST /process for movie trailer`

`POST /process for news summary`

`POST /process for media mill`

`POST /process for nude meta`

`GET /process`

`GET /process/{id}`

`PUT /process/ {id}`

`DELETE /process/{id}`

`GET /process/ {id}/ errors`

`GET /process/ {id}/ inputs`

`GET /process/ {id}/ progress`

`GET /process/{id}/result`

`POST /process/{id}/tag`

`DELETE /process/{id}/tag`