Summary API

Simply send a POST request to https://api.mediamachine.io/summary/gif or https://api.mediamachine.io/summary/mp4 with the attributes described below.

Here is a quick link to a simple request payload example...


Parameter definitions#

NameTypeRequiredDescription
apiKeystringtrueyour MediaMachine api key
inputUrlURL Stringtruelocation of the input file
outputUrlURL Stringtruelocation where output should be uploaded
inputCredsCredentials Objectfalserequired if your input is stored in a bucket
outputCredsCredentials Objectfalserequired if the output should be stored in a bucket
widthintfalsesummary width - defaults to width of input video
removeAudioboolfalseif true, audio is removed from video outputs
successUrlhttp url stringfalsecallback url when summary is successfully created
failureUrlhttp url stringfalsecallback url if summary creation fails
watermarkWatermark Objectfalseoptional watermark

URL-String#

You can specify the input/output locations using a flexible url scheme depending on where your data is stored. Any of the following forms are accepted.

https://yourdomain/input/video.mp4
s3://yourbucket/input/video.mp4
azure://yourbucket/input/video.mp4
gcp://yourbucket/input/video.mp4

Credentials Object#

Make sure credentials are as narrowly scoped as possible

AWS Credentials#

NameTypeRequiredDescription
regionstringtrues3 bucket region
accessKeyIdstringtrueaws access key
secretAccessKeystringtrueaws secret access key

Azure Credentials#

NameTypeRequiredDescription
accountNamestringtrueazure account name
accountKeystringtrueazure account key

GCP Credentials#

You can send the Google service key JSON contents as GCP bucket credentials

Watermark Object#

You can optionally specify attach a watermark object with your request to add a watermark to the output. A watermark can be any one of the following types:

Text Watermark#

NameTypeRequiredDescription
textstringtrueThe watermark text
fontSizeinttrueThe font size for the watermark
fontColorstringfalseThe color for the watermark text. Default: white
positionstringfalseThe position of the watermark. OneOf: {topLeft,topRight,bottomLeft,bottomRight}. Default: bottomRight
opacityfloatfalseThe opacity for the watermark. Between [0,1]. Default: 0.9

Image URL Watermark#

If you want to use an image as a watermark, you can provide the image url along with the watermark payload.

NameTypeRequiredDescription
imageUrlhttp url stringtrueThe url for the watermark image
heightinttrueThe watermark height. Cannot be <=0
widthinttrueThe watermark width. Cannot be <=0
positionstringfalseThe position of the watermark. OneOf: {topLeft,topRight,bottomLeft,bottomRight}. Default: bottomRight
opacityfloatfalseThe opacity for the watermark. Between [0,1]. Default: 0.9

Image Name Watermark#

If you have uploaded a watermark image to your MediaMachine organization account, you can simply use the key of the image as a handy reference.

NameTypeRequiredDescription
imageNamestringtrueThe reference name of the image uploaded to your MediaMachine account
heightinttrueThe watermark height. Cannot be <=0
widthinttrueThe watermark width. Cannot be <=0
positionstringfalseThe position of the watermark. OneOf: {topLeft,topRight,bottomLeft,bottomRight}. Default: bottomRight
opacityfloatfalseThe opacity for the watermark. Between [0,1]. Default: 0.9

POST /summary/mp4#

Send a request to this endpoint to get a video summary in mp4 format. The request payload looks exactly same as described for gif summary below.

POST /summary/gif#

Send a request to this endpoint to get a video summary in gif format.

Videos stored on s3/azure/gcp#

If your source video file is stored on s3 or other bucket stores, you can use a URL-String style inputUrl to point to the video file location. MediaMachine can upload the results s3 (same or different bucket) as well. Use the outputUrl to specify the output destination.

{
"apiKey": "Your MediaMachine API key",
"successUrl": "https://yourdomain.com/success",
"failureUrl": "https://yourdomain.com/failure",
"width": 150, // Optional - defaults to video size
"removeAudio": true, // Optional - defaults to false
"inputUrl": "s3://yourbucket/files/video.mp4",
// Use the creds object matching your store of choice (s3/azure/gcp)
"inputCreds": {
"region": "s3 bucket region like: us-east-1",
"accessKeyId": "your aws access key id",
"secretAccessKey": "your aws secret access key"
},
// You can mix-and-match input/output destinations
// For example s3 input and http-server/azure/gcp output
"outputUrl": "s3://yourbucket/files/video-summary.{mp4,gif}",
"outputCreds": {
// These can be different than input creds too
"region": "us-east-1",
"accessKeyId": "your aws access key id",
"secretAccessKey": "your aws secret access key"
},
// Text watermark example
"watermark": {
"text": "mediamachine.io",
"fontSize": 12,
"fontColor": "white",
"position": "topLeft",
"opacity": 0.9
}
}

Videos stored on file servers#

If your source video file is stored on a file server, you can use simply point the inputUrl to the video file location. We can upload the results to the same file server, use the outputUrl to specify the output destination.

{
"apiKey": "Your MediaMachine API key",
"successUrl": "https://yourdomain.com/success",
"failureUrl": "https://yourdomain.com/failure",
"inputUrl": "https://yourdomain.com/files/video.mp4",
"outputUrl": "https://yourdomain.com/files/video-summary.{mp4,gif}",
"width": 150, // Optional - defaults to video size
"removeAudio": true // Optional - defaults to false
}

Responses#

StatusMeaningDescription
200OKJob accepted
othersErrorRequest errored or invalid input

Example response#

{
"id": "00000000-0000-0000-0000-000000000000",
"status": "queued",
"createdAt": "2021-02-15T17:34:16.116644Z"
}

Example error response#

{
"error": "invalid inputUrl"
}