Summary API

MediaMachine creates engaging video preview Summaries from input videos.

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

Name	Type	Required	Description
apiKey	string	true	your MediaMachine api key
inputUrl	URL String	true	location of the input file
outputUrl	URL String	true	location where output should be uploaded
inputCreds	Credentials Object	false	required if your input is stored in a bucket
outputCreds	Credentials Object	false	required if the output should be stored in a bucket
width	int	false	summary width - defaults to width of input video
removeAudio	bool	false	if true, audio is removed from video outputs
successUrl	http url string	false	callback url when summary is successfully created
failureUrl	http url string	false	callback url if summary creation fails
watermark	Watermark Object	false	optional 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

A credentials object can be any of the following types:

Make sure credentials are as narrowly scoped as possible

AWS Credentials

Name	Type	Required	Description
region	string	true	s3 bucket region
accessKeyId	string	true	aws access key
secretAccessKey	string	true	aws secret access key

Azure Credentials

Name	Type	Required	Description
accountName	string	true	azure account name
accountKey	string	true	azure 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

Name	Type	Required	Description
text	string	true	The watermark text
fontSize	int	true	The font size for the watermark
fontColor	string	false	The color for the watermark text. Default: white
position	string	false	The position of the watermark. OneOf: {topLeft,topRight,bottomLeft,bottomRight}. Default: bottomRight
opacity	float	false	The 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.

Name	Type	Required	Description
imageUrl	http url string	true	The url for the watermark image
height	int	true	The watermark height. Cannot be <=0
width	int	true	The watermark width. Cannot be <=0
position	string	false	The position of the watermark. OneOf: {topLeft,topRight,bottomLeft,bottomRight}. Default: bottomRight
opacity	float	false	The 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.

Name	Type	Required	Description
imageName	string	true	The reference name of the image uploaded to your MediaMachine account
height	int	true	The watermark height. Cannot be <=0
width	int	true	The watermark width. Cannot be <=0
position	string	false	The position of the watermark. OneOf: {topLeft,topRight,bottomLeft,bottomRight}. Default: bottomRight
opacity	float	false	The 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

Status	Meaning	Description
200	OK	Job accepted
others	Error	Request 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"

}