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

To be able to send API requests, you need to authorize.

We offer two options on how you can get your authorization token (API key):

  • Register via the UI and get your authorization token according to the following instruction:
    1. Sign in to our 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. Get 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.

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, and all sports Trailer compilation pipelines
disabled_modulesNames of modules to disable in the processarray of stringOptional
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
proxy_enabledTrue to enable proxy file generation; otherwise, falseBoolean
start_msThe start time of the segment to process (in milliseconds)numberDefault value is 0
titleProcess namestringRequired
Cannot be empty
typeProcess typestringRequired
Case sensitive
video_urlsLink to the video(s) to processarray of string

Example value:


    {
        "config": {
          "additionalProp1": {}
        },
        "disabled_modules": [
          "string"
        ],
        "live_config": {
          "enable": false
        },
        "meta": {
          "end_ms": 0,
          "proxy_enabled": true,
          "start_ms": 0
        },
        "title": "string",
        "type": "string",
        "video_urls": [
          "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
createdProcess creation timestringTime is GMT
account_idAccount IDstring
processing_timeTime required for video processing in secondsstringValid format: Ns
N — number of s — seconds
processing_time_millisTime required for video processing in millisecondsnumber
processing_time_millisTime required for video processing in millisecondsnumber
is_lifeTrue if the process is created for a live streaming; otherwise, falseBoolean
tagsProcess tagsobjectTags can be added using POST /process/ {id}/ tag endpoint
metaMetadata settingsmetadata objectOptional
proxy_enabledTrue if the proxy file generation is enabled; 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",
      "video_urls": [
        "https://aihunters-media-files.s3.eu-west-1.amazonaws.com/videos/series/15.mp4"
      ]
    }'    
  

Response body:


    {
        "id": "1b798676-56f8-4185-9a09-eaea8c823779",
        "title": "SkipMetaExample",
        "type": "Skip meta",
        "status": "creating",
        "created": "2022-03-02T12:01:58.017306Z",
        "account_id": "a079bdee-0353-4fa1-8130-0ed76497f8b6",
        "processing_time": "0s",
        "processing_time_millis": 0,
        "is_live": false,
        "tags": {},
        "meta": {
          "proxy_enabled": 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.

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": "c3fae01e-d910-4467-9366-b3f199a6b2d5"
      },
      "live_config": {
        "enable": false
      },
      "title": "LaligaDetectionExample",
      "type": "Graphics meta",
      "video_urls": [
        "https://aihunters-media-files.s3.eu-west-1.amazonaws.com/videos/BarcaMadrid.mp4"
      ]
    }'    
  

Response body:


    {
        "id": "c0992ee4-14e5-4c29-a1ff-069c15977f50",
        "title": "LaligaDetectionExample",
        "type": "Graphics meta",
        "status": "creating",
        "created": "2022-03-03T09:55:40.026992Z",
        "account_id": "a079bdee-0353-4fa1-8130-0ed76497f8b6",
        "processing_time": "0s",
        "processing_time_millis": 0,
        "is_live": false,
        "tags": {},
        "meta": {
          "proxy_enabled": 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 '{
   "meta": {
    "proxy_enabled": true
  },
  "title": "CastMetaExample",
  "type": "Cast meta",
  "video_urls": [
    "https://aihunters-media-files.s3.eu-west-1.amazonaws.com/videos/series/16.mp4"
  ]
}'

Response body:


    {
        "id": "801fa67b-1a2e-4b00-8468-d921c3fc45ae",
        "title": "CastMetaExample",
        "type": "Cast meta",
        "status": "creating",
        "created": "2022-03-03T09:55:40.026992Z",
        "account_id": "a079bdee-0353-4fa1-8130-0ed76497f8b6",
        "processing_time": "0s",
        "processing_time_millis": 0,
        "is_live": false,
        "tags": {},
        "meta": {
          "proxy_enabled": true
        }
      }    
      
  

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",
  "video_urls": [
    "https://aihunters-media-files.s3.eu-west-1.amazonaws.com/videos/series/17.mp4"
  ]
}'

Response body:


    {
        "id": "801fa67b-1a2e-4b00-8468-d921c3fc45ae",
        "title": "CropMetaExample",
        "type": "Crop meta",
        "status": "creating",
        "created": "2022-03-03T09:55:40.026992Z",
        "account_id": "a079bdee-0353-4fa1-8130-0ed76497f8b6",
        "processing_time": "0s",
        "processing_time_millis": 0,
        "is_live": false,
        "tags": {},
        "meta": {
          "proxy_enabled": 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",
      "video_urls": [
        "https://aihunters-media-files.s3.eu-west-1.amazonaws.com/videos/soccer/18.mp4"
      ]
    }'    

Response body:


    {
        "id": "801fa67b-1a2e-4b00-8468-d921c3fc45ae",
        "title": "SoccerMetaExample",
        "type": "Soccer meta",
        "status": "creating",
        "created": "2022-03-03T09:55:40.026992Z",
        "account_id": "a079bdee-0353-4fa1-8130-0ed76497f8b6",
        "processing_time": "0s",
        "processing_time_millis": 0,
        "is_live": false,
        "tags": {},
        "meta": {
          "proxy_enabled": false
        }
      }          
      
  

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": {
        "highlights": {
          "window_size": 20,
          "highlight_len": 150,
          "goal_distrib": [
            0,
            0.45,
            0,
            0.15,
            0.4
          ],
          "save_chronology": true,
          "use_double_labels": false,
          "types": [
            "high drama",
            "operator based",
            "mid",
            "attacks",
            "tense"
          ]
       }               
     

The default configuration for Basketball trailer compilation and Hockey trailer compilation is the following:


      "config": {
        "config": {
        "highlights": {
          "goal_distrib": [
            0,
            0.15,
            0.45,
            0.25,
            0.15,
            0
          ],
          "highlight_len": 150,
          "save_chronology": true,
          "use_double_labels": false,
          "window_size": 500
        }
      }
     

The default configuration for American football trailer compilation is the following:


      "config": {
        "config": {
        "highlights": {
          "goal_distrib": [
            0.6,
            0.2,
            0.2
          ],
          "highlight_len": 300,
          "save_chronology": true,
          "use_double_labels": true,
          "window_size": 100
        }
      }
     

The trailer compilation process requires segments from the meta JSON file.

Snippet of an example Soccer trailer compilation process with only 2 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 '{
  "config": {
     "config": {
 "highlights": {
   "window_size": 20,
   "highlight_len": 150,
   "goal_distrib": [
     0,
     0.45,
     0,
     0.15,
     0.4
   ],
   "save_chronology": true,
   "use_double_labels": false,
   "types": [
     "high drama",
     "operator based",
     "mid",
     "attacks",
     "tense"
   ]
} 
}
},
"meta": {
  "segments": [
     {
      "anomaly_score": 1,
      "dynamics_score": 0.548,
      "dynamics_type": "slow motion",
      "end": {
        "ms": 5879440
      },
      "label": "Side content",
      "median_area_person": 0.001,
      "median_person_quantity_for_frame": 4,
      "normalised_dynamics_score": 0.03459595959596127,
      "segments": [
        {
          "end": {
            "ms": 5866880
          },
          "start": {
            "ms": 5863600
          },
          "type": "subshot"
        },
        {
          "end": {
            "ms": 5869760
          },
          "start": {
            "ms": 5866920
          },
          "type": "subshot"
        },
        {
          "end": {
            "ms": 5879440
          },
          "start": {
            "ms": 5869800
          },
          "type": "subshot"
        },
        {
          "dynamics_score": 0,
          "end": {
            "ms": 5866880
          },
          "label": "Close-up (Face)",
          "start": {
            "ms": 5863600
          },
          "type": "subshot"
        },
        {
          "dynamics_score": 0,
          "end": {
            "ms": 5869760
          },
          "label": "Full height",
          "start": {
            "ms": 5866920
          },
          "type": "subshot"
        },
        {
          "dynamics_score": 0,
          "end": {
            "ms": 5879440
          },
          "label": "Whole field",
          "start": {
            "ms": 5869800
          },
          "type": "subshot"
        }
      ],
      "start": {
        "ms": 5863600
      },
      "type": "shot"
    }
  ]
},
"title": "SoccerTrailersExample",
  "type": "Soccer trailer compilation"
}'

Response body:


    {
        "id": "938433c9-a8b3-439e-b249-469f200770f3",
        "title": "SoccerTrailersExample",
        "type": "Soccer trailer compilation",
        "status": "creating",
        "created": "2022-03-03T22:05:19.871079Z",
        "account_id": "a079bdee-0353-4fa1-8130-0ed76497f8b6",
        "processing_time": "0s",
        "processing_time_millis": 0,
        "is_live": false,
        "tags": {},
        "meta": {
          "proxy_enabled": false
        }
      }        
      
  

POST /process for Movie trailer

Creates a Movie trailer process

Note that a Movie trailer process requires the following trailer length configuration:


        "config": {
            "external_config": {
          "trailer": {
            "length": number
          }            
     

The trailer length should be set in seconds.

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": {
    "external_config": {
  "trailer": {
    "length": 60
  }
}
  },
  "title": "MovieTrailerExample",
  "type": "Movie trailer",
  "video_urls": [
    "https://aihunters-media-files.s3.eu-west-1.amazonaws.com/movies/The-Devil-Wears-Prada.mp4"
  ]
}'
  

Response body:


    {
        "id": "c0992ee4-14e5-4c29-a1ff-069c15977f50",
        "title": "MovieTrailerExample",
        "type": "Movie trailer",
        "status": "creating",
        "created": "2022-03-03T09:55:40.026992Z",
        "account_id": "a079bdee-0353-4fa1-8130-0ed76497f8b6",
        "processing_time": "0s",
        "processing_time_millis": 0,
        "is_live": false,
        "tags": {},
        "meta": {
          "proxy_enabled": false
        }
      }      
      
  

POST /process for News summary

Creates a News summary process

Note that a News summary process requires the following external configuration:


      "config":{
        "external_config":{
          "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": "NewsSummary Example #1",
  "type": "News summary",
  "video_urls": [
    "https://aihunters-media-files.s3.eu-west-1.amazonaws.com/Permanent+Cluster+Run/News/sport/After+The+Olympic+Games_+The+Costly+Problem+Of+Leftover+Stadiums+_+NBC+News.mp4"
  ],
  "config":{
"external_config":{
  "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": "94f906a0-ddb6-4f97-82fe-377b4a4e3832",
      "title": "NewsSummary Example #1",
      "type": "News summary",
      "status": "creating",
      "created": "2022-05-03T10:28:36.814576Z",
      "account_id": "a079bdee-0353-4fa1-8130-0ed76497f8b6",
      "processing_time": "0s",
      "processing_time_millis": 0,
      "is_live": false,
      "tags": {},
      "meta": {
        "proxy_enabled": 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.

Valid trailer types are:

For movies:

  • diversity_trailer

For sports:

  • high drama
  • operator based
  • tense
  • attacks
  • mid

For crop and cast:

  • out

The Media Mill process requires segments with start and end time (trailer.json) given in milliseconds to generate the output media.

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 '{
  "type": "Media mill",
    "title": "MediaMillExample",
    "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
        }
      }
    ]
        }
    },
    "video_urls": [
        "https://aihunters-media-files.s3.eu-west-1.amazonaws.com/movies/Pirates+Of+The+Caribbean+-+The+Curse+Of+The+Black+Pearl.mp4"
    ]
}'
  

Response body:


    {
        "id": "938433c9-a8b3-439e-b249-469f200770f3",
        "title": "MediaMillExample",
        "type": "Media mill",
        "status": "creating",
        "created": "2022-03-03T22:05:19.871079Z",
        "account_id": "a079bdee-0353-4fa1-8130-0ed76497f8b6",
        "processing_time": "0s",
        "processing_time_millis": 0,
        "is_live": false,
        "tags": {},
        "meta": {
          "proxy_enabled": 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
Statuses for filtration must be separated 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, copying

Example process:

Where "Type": "Cast meta" and "Offset": 3


    curl -X 'GET' \
    'https://api.cognitivemill.com/api/v1/process?type=Cast%20meta&offset=3' \
      -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, copying
createdProcess creation timestringTime is GMT
account_idAccount IDstring
processing_timeTime required for video processing in secondsstringValid format: Ns
N — number of s — seconds
processing_time_millisTime required for video processing in millisecondsnumber
is_lifeTrue if the process is created for a live streaming; otherwise, falseBoolean
tagsProcess tagsobject
metaMetadatametadata object
resultsProcess outputarray of object
nameResult namestringValid names:
meta — for all metadata processes;
trailer — for trailer compilation processes;
[name of trailer preset] — for Media mill processes.
For example: high drama, operator based, mid, etc. for sports, and diversity_trailer for movies.
typeOutput typestringValid types: json, media
proxy_enabledTrue if the proxy file generation is enabled; otherwise, falseBoolean

Response body:


    {
        "pagination": {
          "limit": 0,
          "offset": 3,
          "total": 17
        },
        "processes": [
          {
            "id": "32401bb9-a296-4960-95db-906a61ccf623",
            "title": "ExampleVideo",
            "type": "Cast meta",
            "status": "completed",
            "created": "2022-01-04T09:32:08.667925Z",
            "account_id": "a079bdee-0353-4fa1-8130-0ed76497f8b6",
            "processing_time": "0s",
            "processing_time_millis": 0,
            "is_live": false,
            "tags": {},
            "meta": {
              "results": [
                {
                  "name": "meta",
                  "type": "json"
                }
              ],
              "proxy_enabled": 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
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
createdProcess creation timestringTime is GMT
account_idAccount IDstring
processing_timeTime required for video processing in secondsstringValid format: Ns
N — number of s — seconds
processing_time_millisTime required for video processing in millisecondsnumber
is_lifeTrue if the process is created for a live streaming; otherwise, falseBoolean
tagsProcess tagsobject
metaMetadatametadata object
resultsProcess outputarray of object
nameResult namestringValid names:
meta — for all metadata processes;
trailer — for trailer compilation processes;
[name of trailer preset] — for Media mill processes.
For example: high drama, operator based, mid, etc. for sports, and diversity_trailer for movies.
typeOutput typestringValid types: json, media
proxy_enabledTrue if the proxy file generation is enabled; otherwise, falseBoolean

Response body:


        {
          "id": "32401bb9-a296-4960-95db-906a61ccf623",
          "title": "ExampleVideo",
          "type": "Cast meta",
          "status": "completed",
          "created": "2022-01-04T09:32:08.667925Z",
          "account_id": "a079bdee-0353-4fa1-8130-0ed76497f8b6",
          "processing_time": "0s",
          "processing_time_millis": 0,
          "is_live": false,
          "tags": {},
          "meta": {
            "results": [
              {
                "name": "meta",
                "type": "json"
              }
            ],
            "proxy_enabled": false
          }
        }
    
  

PUT /process/ {id}

Edits the process title

Request

ElementDescriptionTypeNotes
idProcess IDstringRequired
userEdit process formobjectRequired
titleProcess name to editstringRequired

Example process:


        curl -X 'PUT' \
'https://api.cognitivemill.com/api/v1/process/931c1659-9a84-41d4-843a-a9d86bcad62a' \
  -H 'accept: application/json' \
  -H 'api-token: 0***********************9' \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "NewName"
}'       
    

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
createdProcess creation timestringTime is GMT
account_idAccount IDstring
processing_timeTime required for video processing in secondsstringValid format: Ns
N — number of s — seconds
processing_time_millisTime required for video processing in millisecondsnumber
is_lifeTrue if the process is created for a live streaming; otherwise, falseBoolean
tagsProcess tagsobject
metaMetadatametadata object
resultsProcess outputarray of object
nameResult namestringValid names:
meta — for all metadata processes;
trailer — for trailer compilation processes;
[name of trailer preset] — for Media mill processes.
For example: high drama, operator based, mid, etc. for sports, and diversity_trailer for movies.
typeOutput typestringValid types: json, media
proxy_enabledTrue if the proxy file generation is enabled; otherwise, falseBoolean

Response body:


    {
        "id": "931c1659-9a84-41d4-843a-a9d86bcad62a",
        "title": "NewName",
        "type": "Soccer meta",
        "status": "completed",
        "created": "2022-03-04T11:36:50.502043Z",
        "account_id": "a079bdee-0353-4fa1-8130-0ed76497f8b6",
        "processing_time": "19m43.976s",
        "processing_time_millis": 1183976,
        "is_live": false,
        "tags": {},
        "meta": {
          "results": [
            {
              "name": "meta",
              "type": "json"
            }
          ],
          "proxy_enabled": 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/32401bb9-a296-4960-95db-906a61ccf623' \
          -H 'accept: application/json' \
          -H 'api-token: 0***********************9' \               
    

Response body:


    "success"
  

GET /process/ {id}/ channels

Returns channel URL for live streaming by process ID

Note that first you must create a Graphics meta process with the configuration for live streamings enabled:


        "live_config": {
            "enable": true
          }                 
     

After the process is created, take the process ID and use GET /process/ {id}/ channels to get the channel for your live streaming.

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
idProcess IDstring
stream_urlReturned channel URL for live streamingstring
video_idVideo IDstring
statusProcess statusstringPossible statuses: idle, active, stopped, finished, failed
stopped_timeTime when the streaming stoppedstring

Response body:


        [
   {
    "id": "16888c0b-f465-44b2-a564-ac787b330024",
    "stream_url": "a3242f0c45fd44050b0ef304153f9b9b-0f2769c83bd0cdc9.elb.eu-west-1.amazonaws.com/live/5318fd81-33e7-497a-88f1-3938d1bf0d90?token=424cba65cce86b43176a01faf0f0440f",
    "video_id": "1709f1f2-7b16-4773-8252-353315286141",
    "status": "idle",
    "stopped_time": "0001-01-01T00:00:00Z"
   }

 ]

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://test-api.cognitivemill.com/api/v1/process/e1082f68-1600-4c26-9449-fbb85af5abfb/errors' \
  -H 'accept: application/json' \
  -H 'api-token: 0***********************9' \              
    

Response body:

Contains an error message.


    "bad status: 403 Forbidden\n"
  

GET /process/ {id}/ progress

Returns the process status by process ID

Request

ElementDescriptionTypeNotes
idProcess IDstringRequired

Example process:


        curl -X 'GET' \
        'https://test-api.cognitivemill.com/api/v1/process/e1082f68-1600-4c26-9449-fbb85af5abfb/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
[module_name]Module name with processing progress data for each moduleobject
valueProcessing progress 0 to 1 for the specified modulenumber
percentProcessing progress in % for the specified modulestring

Response body:


        {
            "progress": 0.1401649,
            "percent": "14.02",
            "features": {
              "Camera motion decision": {
                "value": 0,
                "percent": "0.00"
              },
              "Visual analysis T": {
                "value": 0,
                "percent": "0.00"
              },
              "Content ingestion": {
                "value": 1,
                "percent": "100.00"
              },
              "Soccer field analysis": {
                "value": 0.112426035,
                "percent": "11.24"
              },
              "Soccer decision": {
                "value": 0,
                "percent": "0.00"
              },
              "Soccer visual analysis": {
                "value": 0.082840234,
                "percent": "8.28"
              },
              "Person detection": {
                "value": 0.13609467,
                "percent": "13.61"
              },
              "Shot splitting": {
                "value": 0,
                "percent": "0.00"
              },
              "Motion perception": {
                "value": 0.3668639,
                "percent": "36.69"
              }
            }
          }
          
      

GET /process/ {id}/ result

Returns one process result by the process ID and result name

Request

ElementDescriptionTypeNotes
typeResult namestringThough the element is called “type”, you need to enter the result “name” to send this request.
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 an example of a meta JSON file for a Skip meta process:

Response body


            {
                "segments": [
                  {
                    "end": {
                      "ms": 231840,
                      "time": "0:03:51.840000"
                    },
                    "start": {
                      "ms": 220960,
                      "time": "0:03:40.960000"
                    },
                    "type": "standout end credits"
                  }
                ],
                "time_markers": [
                  {
                    "ms": 220960,
                    "time": "0:03:40.960000",
                    "type": "standout end credits"
                  },
                  {
                    "ms": 220960,
                    "time": "0:03:40.960000",
                    "type": "safe point"
                  }
                ]
              }
              
        

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}/ result

Adds a new process result to a process

With this method, you can add edited meta in JSON format to an existing process.

Request

ElementDescriptionTypeNotes
idProcess IDstringRequired
processProcess results to addobjectRequired
nameResult name to addstringRequired
meta — for all metadata processes;
trailer — for trailer compilation processes;
[name of trailer preset] — for a Media mill process. For example: high drama, operator based, mid, etc. for sports, and diversity_trailer for movies.
valueResult value to addobjectFor example, here you can paste an edited meta JSON.

Example process:


        curl -X 'POST' \
'https://api.cognitivemill.com/api/v1/process/9f64c881-a77e-43e5-8577-a409f60da693/results' \
  -H 'accept: application/json' \
  -H 'api-token: 0***********************9' \
  -H 'Content-Type: application/json' \
  -d '{
"name": "meta",
    "value": {
    "segments": [
      {
        "end": {
          "ms": 231840,
          "time": "0:03:51.840000"
        },
        "start": {
          "ms": 220960,
          "time": "0:03:40.960000"
        },
        "type": "standout end credits"
      }
    ],
    "time_markers": [
      {
        "ms": 221960,
        "time": "0:03:40.960000",
        "type": "standout end credits"
      },
      {
        "ms": 220960,
        "time": "0:03:40.960000",
        "type": "safe point"
      }
    ]
  }
  }'        
    

Response

ElementDescriptionTypeNotes
idResult IDstring
nameResult namestringValid names:
meta — for all metadata processes;
trailer — for trailer compilation processes;
[name of trailer preset] — for a Media mill process. For example: high drama, operator based, mid, etc. for sports, and diversity_trailer for movies.
is_originalTrue if the video is original; otherwise, falseBoolean

Response body


        {
            "id": "9c1a3b02-a65a-4f15-bbfa-3bec45920261",
            "name": "meta",
            "is_original": false
          }
          
        

DELETE / process/ {id}/ result

Removes process result by the process ID and result name

Request

ElementDescriptionTypeNotes
idProcess IDstringRequired
processProcess results to deleteobjectRequired
nameResult name to deletestringRequired
meta — for all metadata processes;
trailer — for trailer compilation processes;
[name of trailer preset] — for a Media mill process. For example: high drama, operator based, mid, etc. for sports, and diversity_trailer for movies.

Example process:


        curl -X 'DELETE' \
        'https://api.cognitivemill.com/api/v1/process/9f64c881-a77e-43e5-8577-a409f60da693/results' \
          -H 'accept: application/json' \
          -H 'api-token: 0***********************9' \
          -H 'Content-Type: application/json' \
          -d '{
          "name": "meta"
        }'        
    

Response body


        "success"  
    

GET /process/ {id}/ results

Returns a list of all process results with their IDs and names by process ID

Request

ElementDescriptionTypeNotes
idProcess IDstringRequired

Example process:


        curl -X 'GET' \
'https://api.cognitivemill.com/api/v1/process/9f64c881-a77e-43e5-8577-a409f60da693/results' \
  -H 'accept: application/json' \
  -H 'api-token: 0***********************9' \   
    

Response

ElementDescriptionTypeNotes
idResult IDstring
nameResult namestringValid names:
meta — for all metadata processes;
trailer — for trailer compilation processes;
[name of trailer preset] — for a Media mill process. For example: high drama, operator based, mid, etc. for sports, and diversity_trailer for movies.
is_originalTrue if the video is original; otherwise, falseBoolean

Response body


        [
        {
          "id": "d9a53e5f-cebd-415b-8709-753601b6c353",
          "name": "high drama",
          "is_original": true
        },
        {
          "id": "a232bcc2-8996-4e55-a6f9-1361eb898bc1",
          "name": "operator based",
          "is_original": true
        },
        {
          "id": "503ecc52-8706-4738-bc77-8fb4045c0dcc",
          "name": "mid",
          "is_original": true
        }
      ]       
        

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
Tag key is displayed in the Process tags section in the Cognitive Mill visualizer.
valueTag valuestringRequired
Valid values: letters, numbers, and underscores

Example process:


            curl -X 'POST' \
            'https://api.cognitivemill.com/api/v1/process/f4e1e81b-a6ad-491a-af37-f1f74c4ce5cd/tag' \
              -H 'accept: application/json' \
              -H 'api-token: 0***********************9' \
              -H 'Content-Type: application/json' \
              -d '{
              "tags": [
                {
                  "key": "endCredits",
                  "value": "1"
                }
              ]
            }'              
        

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
createdProcess creation timestringTime is GMT
account_idAccount IDstring
processing_timeTime required for video processing in secondsstringValid format: Ns
N — number of s — seconds
processing_time_millisTime required for video processing in millisecondsnumber
is_lifeTrue if the process is created for a live streaming; otherwise, falseBoolean
tagsProcess tagsobject
[tag_key]Process tag key-value pairstringTag key is displayed in the Process tags section in the Cognitive Mill visualizer.
metaMetadatametadata object
resultsProcess outputarray of object
nameResult namestringValid names:
meta — for all metadata processes;
trailer — for trailer compilation processes;
[name of trailer preset] — for Media mill processes.
For example: high drama, operator based, mid, etc. for sports, and diversity_trailer for movies.
typeOutput type (result type)stringValid types: json, media
proxy_enabledTrue if the proxy file generation is enabled; otherwise, falseBoolean

Response body:


    {
        "id": "f4e1e81b-a6ad-491a-af37-f1f74c4ce5cd",
        "title": "SkipMeta",
        "type": "Skip meta",
        "status": "completed",
        "created": "2022-03-07T13:24:10.532929Z",
        "account_id": "a079bdee-0353-4fa1-8130-0ed76497f8b6",
        "processing_time": "21m33.09s",
        "processing_time_millis": 1293090,
        "is_live": false,
        "tags": {
          "endCredits": "1"
        },
        "meta": {
          "results": [
            {
              "name": "result",
              "type": "json"
            }
          ],
          "proxy_enabled": 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/f4e1e81b-a6ad-491a-af37-f1f74c4ce5cd/tag' \
      -H 'accept: application/json' \
      -H 'api-token: 0***********************9' \
      -H 'Content-Type: application/json' \
      -d '{
      "keys": [
        "endCredits"
      ]
    }'              
  

Response body:


    {
        "id": "f4e1e81b-a6ad-491a-af37-f1f74c4ce5cd",
        "title": "SkipMeta",
        "type": "Skip meta",
        "status": "completed",
        "created": "2022-03-07T13:24:10.532929Z",
        "account_id": "a079bdee-0353-4fa1-8130-0ed76497f8b6",
        "processing_time": "21m33.09s",
        "processing_time_millis": 1293090,
        "is_live": false,
        "tags": {},
        "meta": {
          "results": [
            {
              "name": "result",
              "type": "json"
            }
          ],
          "proxy_enabled": false
        }
      }
      
        
  

The API returns the complete data on the process with the tag deleted as shown in the response body above.

GET /process/ {id}/ videos

Returns video URLs for processed videos by process ID

Request

ElementDescriptionTypeNotes
idProcess IDstringRequired

Example process:


        curl -X 'GET' \
        'https://api.cognitivemill.com/api/v1/process/f4e1e81b-a6ad-491a-af37-f1f74c4ce5cd/videos' \
          -H 'accept: application/json' \
          -H 'api-token: 0***********************9' \                  
    

Response

ElementDescriptionTypeNotes
idVideo IDstring
nameTitle of the videostringName example: Name.mp4
statusStatus of the processstringPossible statuses are: creating, created, ready for downloading, downloading, downloaded, transcoding, transcoded, reading, read, preparation, ready for processing, processing, processed, completion, completed, failed, removing, copying
typeVideo encoding typestringSupported codecs:
MPEG-1
MPEG-2
VC-1
VP-8
VP-9 (8/10/12 bit)
H.264
H.265 (4:2:0/4:4:4) (8/10/12 bit)
process_idProcess IDstring
public_urlLink to public video storagestring
is_originalTrue if the video is original; otherwise, falseBoolean
transcoder_idID of transcoderstring

Response body


        [
  {
    "id": "bacc8d04-424d-4f45-a05d-5df4ce67be93",
    "name": "B-2-God_of_the_Damned.mp4",
    "status": "transcoding",
    "type": "mpeg",
    "process_id": "f4e1e81b-a6ad-491a-af37-f1f74c4ce5cd",
    "public_url": "https://aihunters-media-files.s3.eu-west-1.amazonaws.com/Permanent+Cluster+Run/cognitive+cast/B-2-God_of_the_Damned.mp4",
    "is_original": true,
    "transcoder_id": ""
  }
]
        

Video Management

GET /video/ {id}/ contents

Returns contents of video by video ID

To get video ID, use GET /process/ {id}/ videos

Request

ElementDescriptionTypeNotes
idVideo IDstringRequired

Example process:


        curl -X 'GET' \
        'https://api.cognitivemill.com/api/v1/video/bacc8d04-424d-4f45-a05d-5df4ce67be93/contents' \
          -H 'accept: application/json' \
          -H 'api-token: 0***********************9' \                          
    

Response

ElementDescriptionTypeNotes
idContent IDstring
indexContent indexnumber
public_urlLink to public video storagestring
filenameTitle of the videostringName example: Name.mp4
video_idVideo IDstring
statusStatus of video contentstring
createdContent creation timestringTime is GMT
fileinfoContent file dataobject
framesNumber of frames in the contentnumber
durationContent duration in millisecondsnumber
fpsContent frame ratenumber
metaContent meta to play the content correctly in browserobject
configContent configurationobject

Response body


[
    {
      "id": "4c3d7a91-55d7-41d4-8875-6f911fe36ab9",
      "index": 0,
      "public_url": "https://aihunters-media-files.s3.eu-west-1.amazonaws.com/Permanent+Cluster+Run/cognitive+cast/B-2-God_of_the_Damned.mp4",
      "filename": "B-2-God_of_the_Damned.mp4",
      "video_id": "bacc8d04-424d-4f45-a05d-5df4ce67be93",
      "status": "read",
      "created": "2022-03-07T13:24:10.658177Z",
      "fileinfo": {
        "frames": 5606,
        "duration": 233640,
        "fps": 24,
        "meta": {
          "startTime": 0,
          "timescale": 12288,
          "timeToSample": {
            "sampleCounts": [
              5606
            ],
            "sampleDeltas": [
              512
            ]
          }
        }
      },
      "config": {}
    }
]         
  

Config

GET /preset

Returns IDs and short descriptions of available configurations

No parameters are required to send the request.

Example process:


        curl -X 'GET' \
        'https://api.cognitivemill.com/api/v1/preset' \
          -H 'accept: application/json' \
          -H 'api-token: 0***********************9' \                                
    

Response

ElementDescriptionTypeNotes
idConfiguration IDstring
descriptionShort description of configurationstring

Response body


    [
        {
          "id": "73209445-56a2-424c-badd-fc87b24de05d",
          "description": "UEFA logo detection. Multi-mask support. Video resolution 640x360. Returns the first detected mask frame. No limitations detected."
        }
      ]
      
          },
          "config": {}
        }
      ]      
        

GET /preset/ {id}

Returns full information about the configuration by config ID

To get config ID, use GET /preset.

Request

ElementDescriptionTypeNotes
idConfig IDstringRequired

Example process:


        curl -X 'GET' \
        'https://api.cognitivemill.com/api/v1/preset/73209445-56a2-424c-badd-fc87b24de05d' \
          -H 'accept: application/json' \
          -H 'api-token: 0***********************9' \                                  
    

In the response body, the app returns complete data on the configuration depending on the configuration.

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.


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