Skip to main content

Video REST APIs

Complete API reference for Gumlet video processing and delivery service

note

Currently, these APIs are in public beta.

Authentication#

Every request to the API is authenticated via an API Token. Bearer authentication works by providing the API key in the request header. Specifically, the header looks something like this:

'authorization': 'Bearer <YOUR API KEY>'

POST Create Asset#

https://api.gumlet.com/v1/video/assets#

An asset refers to a media content/video that is processed, stored, and delivered through Gumlet.
This endpoint creates an asset allowing users to ingest media content into the Gumlet system for processing and delivery.

Body Parameters#

ParameterTypeDescription
inputstring

URL or web address of a file that Gumlet should download to create a new asset.

Required: true

source_idstring

Gumlet video source id.

Required: true

profile_idstringProvide profile_id of the previously created profile. This parameter will override all the parameters (except input and source_id) from the video profile.
formatstring

Transcode and deliver the asset in the requested format. The options can be one of mp4, HLS, andMPEG-DASH.

Required: true

tagstringSpecify a text string or identifier which can identify an asset or bunch of assets later.
widthstringResize video with the given width. Can be an absolute value in pixels or a percentage value with the % suffix. Specified values greater than the original asset width will be ignored.
heightstringResize video with the given height. Can be an absolute value in pixels or a percentage value with the % suffix. Specified values greater than the original asset height will be ignored.
resolutionArray

Required resolutions of the transformed asset in case of HLS or MPEG-DASH delivery format. Can be an array of string out of the following values: 120p, 240p, 360p, 480p, 540p, 720p, 1080p and 1440p. Re-sized rendition will retain the input aspect ratio.

Default: all resolutions from 120p to input video resolution.

cropobjectThis transformation can be used to crop the video by defining a rectangular area within the dimensions of the output video.
padobjectThis transformation can be used to add padding to the video.
trimobjectTrim transformation can be used to trim videos based on time duration.
image_overlayobjectImage overlay can be used to brand a video or add a visual label in the form of an image.
text_overlayobjectText overlay can be used to brand a video or add a label in the form of text.
thumbnailstring

This parameter can be used to control which frame is captured from the video as the thumbnail. Can be one or more (comma-separated) of the following values: A float representing the time in seconds from the beginning of the video e.g. 2.5 . A string representing the percentage of the video (a number) from the beginning appended by p or % e.g. 30p or 30%.

Default: 30%

thumbnail_formatstring

Specify the thumbnail image format. Supported formats are jpeg, jpg, png and webp.

Default: png

mp4_accessboolean

Creates mp4 version for download purpose in case of MPEG-DASH or HLS delivery format.

Default: false

per_title_encodingboolean

Gumlet analyzes each input video on a wide range of visual aspects. Based on the analysis, it chooses a unique set of transcoding options for processing the video. This ensures that the output video is of optimal size and best quality.

Default: true

metadataobjectSet of key-value pairs that you can attach to this object. This can be useful for storing additional information.
process_low_resolution_inputboolean

Currently, the minimum supported frame size is 57600 (240x240) pixels for HLS/DASH and 21025 (145x145) pixels for MP4 format. However, enabling this flag will allow Gumlet to simply put your video asset into the specified delivery format without transcoding and optimization. Enabling this flag will cause any kind of specified video transformation to be ignored if you input video asset frame size is lower than the minimum supported frame size for the specified format.

Default: false

curl -L -X POST 'https://api.gumlet.com/v1/video/assets' \
-H 'Authorization: Bearer <YOUR_API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
"input":"https://gumlet.sgp1.digitaloceanspaces.com/video/sample_1.mp4",
"source_id": "5f462c1561cf8a766464ffc4",
"format": "hls"
}'

POST Create Asset Direct Upload#

https://api.gumlet.com/v1/video/assets/upload#

This endpoint creates a video asset allowing to upload the video from the local file system and ingest media content into the Gumlet system for processing and delivery.

Body Parameters are the same as the Create Asset Body Parameters except for input parameter which this endpoint does not take.

curl -L -X POST 'https://api.gumlet.com/v1/video/assets/upload' \
-H 'Authorization: Bearer <YOUR_API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
"source_id": "60b9a48353ff751c601500db",
"format": "hls"
}'

Once you have got upload_url like in the above response example, you'll use the secured URL to make a PUT request that includes the file in the body as following.

curl -v -X PUT -T video.mp4 <upload_url>

GET Get Asset Status#

https://api.gumlet.com/v1/video/assets/:asset_id#

This endpoint retrieves the details of an asset that has previously been created. Given the unique asset_id, Gumlet will return the corresponding asset status.

Path Parameters#

ParameterTypeDescription
asset_idstringAn asset id for the previously created asset.
curl -L -X GET 'https://api.gumlet.com/v1/video/assets/5fce1951df953f1e913f4604' \
-H 'Authorization: Bearer <YOUR_API_KEY>'

GET Filter Assets#

https://api.gumlet.com/v1/video/assets/list/:source_id#

This endpoint list assets on the basis of status and tag for the given source_id. Gumlet will return all assets under the source_id if none of them is passed.

Path Parameters#

ParameterTypeDescription
source_idstringGumlet video source id.

Query Parameters#

ParameterTypeDescription
statusstring

To filter assets on the basis of their current status. Can be specified as a single status value string or comma-separated status values. The status value can be one of queued, processing, ready, errored, and deleted.

Default: queued,processing,ready,errored,deleted

tagstringInput tag on the basis of which assets need to be filtered.
offsetintegerOffset value for a paginated list of assets.
sizeinteger

Page size for the paginated list.

Default: 10

curl -L -X GET 'https://api.gumlet.com/v1/video/assets/list/5f462c1561cf8a766464ffc4?offset=0&size=1&tag=Gumlet' \
-H 'authorization: Bearer <YOUR_API_KEY>'

DELETE Delete Asset#

https://api.gumlet.com/v1/video/assets/:asset_id#

This endpoint removes an asset given its unique asset id. The asset will be removed from storage as well, associated URLs will be inaccessible.

Path Parameters#

ParameterTypeDescription
asset_idstringAn asset id for the previously created asset.
curl -L -X DELETE 'http://api.gumlet.com/v1/video/assets/5f48b955115462793462ab03' \
-H 'authorization: Bearer <YOUR_API_KEY>'