Loading

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

ElementDescriptionTypeNotes
configProcess configurationconfiguration data objectOptional for most pipelines
additionalProp1Process configuration key(s)stringRequired for graphics meta, movie trailer, news summary, and all sports trailer compilation pipelines
disabled_modulesNames of modules to disable in the processarray of stringOptional
inputsLink to the video(s) to processarray of string
live_configConfiguration for a live streaminglive configuration data objectRequired only for live streamings
enableTrue if the process is created for a live streaming; otherwise, falseBoolean
metaMetadata settingsmetadata objectOptional
end_msThe end time of the segment to process (in milliseconds)numberDefault value is 0
start_msThe start time of the segment to process (in milliseconds)numberDefault value is 0
titleProcess namestringRequired
Cannot be empty
typeProcess typestringRequired
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

ElementDescriptionTypeNotes
idProcess IDstring
titleProcess namestring
typeProcess typestring
statusProcess statusstringPossible 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_stageCurrent stage of processstring
created_atProcess creation date and timestringTime is GMT
account_idAccount IDstring
metaMetadatametadata object
liveCurrent status of live processobject
tagsProcess tagsobjectTags can be added using POST /process/{id}/tag endpoint
finished_atProcess completion date and timestring
is_lifeTrue if the process is created for a live streaming; otherwise, falseBoolean

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

ElementDescriptionTypeNotes
typeType of process to filter bystringOptional
Case sensitive
offsetProcess number to start filtering fromintegerOptional
limitNumber of processes to returnintegerOptional
tagsProcess tag(s) to filter bystringOptional
Tags’ format: key=value;key2=value2;key3.subkey=value3
statusesProcess status(es) to filter bystringOptional
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

ElementDescriptionTypeNotes
paginationReturned processes list dataobject
limitNumber of processes to returninteger
offsetProcess number to start filtering frominteger
totalTotal number of processes meeting filtering criteriainteger
processesList of returned processesarray of objects
idProcess IDstring
titleProcess namestring
typeProcess typestring
statusProcess statusstringPossible 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_stageCurrent stage of processstring
created_atProcess creation timestringTime is GMT
account_idAccount IDstring
metaMetadatametadata object
resultsProcess outputarray of object
nameResult namestringValid names:
contents
meta
trailer
shots
typeOutput typestringValid types: json, media
liveCurrent status of live processobject
tagsProcess tagsobject
finished_atProcess completion date and timestring
is_lifeTrue if the process is created for a live streaming; otherwise, falseBoolean

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

ElementDescriptionTypeNotes
idProcess IDstringRequired

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

ElementDescriptionTypeNotes
paginationReturned processes list dataobject
limitNumber of processes to returninteger
offsetProcess number to start filtering frominteger
totalTotal number of processes meeting filtering criteriainteger
processesList of returned processesarray of objects
idProcess IDstring
titleProcess namestring
typeProcess typestring
statusProcess statusstringPossible 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_stageCurrent stage of processstring
created_atProcess creation timestringTime is GMT
account_idAccount IDstring
metaMetadatametadata object
resultsProcess outputarray of object
nameResult namestringValid names:
contents
meta
trailer
shots
typeOutput typestringValid types: json, media
liveCurrent status of live processobject
tagsProcess tagsobject
finished_atProcess completion date and timestring
is_lifeTrue if the process is created for a live streaming; otherwise, falseBoolean

PUT /process/ {id}

Edits the process title

Request

ElementDescriptionTypeNotes
idProcess IDstringRequired
processFormEdit process formobjectRequired
titleProcess name to editstringRequired

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

ElementDescriptionTypeNotes
paginationReturned processes list dataobject
limitNumber of processes to returninteger
offsetProcess number to start filtering frominteger
totalTotal number of processes meeting filtering criteriainteger
processesList of returned processesarray of objects
idProcess IDstring
titleProcess namestring
typeProcess typestring
statusProcess statusstringPossible 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_stageCurrent stage of processstring
created_atProcess creation timestringTime is GMT
account_idAccount IDstring
metaMetadatametadata object
resultsProcess outputarray of object
nameResult namestringValid names:
contents
meta
trailer
shots
typeOutput typestringValid types: json, media
liveCurrent status of live processobject
tagsProcess tagsobject
finished_atProcess completion date and timestring
is_lifeTrue if the process is created for a live streaming; otherwise, falseBoolean

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

ElementDescriptionTypeNotes
idProcess IDstringRequired

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

ElementDescriptionTypeNotes
idProcess IDstringRequired

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

ElementDescriptionTypeNotes
idProcess IDstringRequired

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

ElementDescriptionTypeNotes
idInput IDstring
urlReturned channel URL for live streamingstring
created_atProcess creation timestringTime is GMT
process_idProcess IDstring
indexNumerical order of inputsinteger

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

ElementDescriptionTypeNotes
idProcess IDstringRequired

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

ElementDescriptionTypeNotes
progressProcessing progress 0 to 1 for the whole processnumber
percentProcessing progress in % for the whole processstring
featuresObject of modules used in the processobject
typeModule name with processing progress data for each moduleobject
valueProcessing progress 0 to 1 for the specified modulenumber
percentProcessing progress in % for the specified modulestring
IndexNumerical order of the moduleinteger

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

ElementDescriptionTypeNotes
typeResult namestringThough 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.
idProcess IDstringRequired

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

ElementDescriptionTypeNotes
idProcess IDstringRequired
userForm for adding tagsobjectRequired
tagsKey-value pairs for tagging a processarray of stringRequired
key=value tag can be used for filtering in GET /process
keyTag keystringRequired
Valid values: letters, numbers, and underscores
valueTag valuestring, number, objectRequired
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

ElementDescriptionTypeNotes
paginationReturned processes list dataobject
limitNumber of processes to returninteger
offsetProcess number to start filtering frominteger
totalTotal number of processes meeting filtering criteriainteger
processesList of returned processesarray of objects
idProcess IDstring
titleProcess namestring
typeProcess typestring
statusProcess statusstringPossible 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_stageCurrent stage of processstring
created_atProcess creation timestringTime is GMT
account_idAccount IDstring
metaMetadatametadata object
resultsProcess outputarray of object
nameResult namestringValid names:
contents
meta
trailer
shots
typeOutput typestringValid types: json, media
liveCurrent status of live processobject
tagsProcess tagsobject
finished_atProcess completion date and timestring
is_lifeTrue if the process is created for a live streaming; otherwise, falseBoolean

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

ElementDescriptionTypeNotes
idProcess IDstringRequired
userForm for deleting tagsobjectRequired
keysKeys of the tags to deletearray of stringRequired

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.


We use cookies to ensure that we give you the best experience on our website. Read cookies policies.