Video APIs

Complete API reference for Gumlet video processing and delivery service

Currently, these APIs are in private beta, please contact [email protected] for enabling them.

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

Parameter

Type

Description

input

string

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

Required: true

source_id

string

Gumlet video source id.

Required: true

profile_id

string

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

format

string

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

Required: true

tag

string

Specify a text string or identifier which can identify an asset or bunch of assets later.

width

string

Resize 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.

height

string

Resize 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.

resolution

Array

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.

crop

object

This transformation can be used to crop the video by defining a rectangular area within the dimensions of the output video.

pad

object

This transformation can be used to add padding to the video.

trim

object

Trim transformation can be used to trim videos based on time duration.

image_overlay

object

Image overlay can be used to brand a video or add a visual label in the form of an image.

text_overlay

object

Text overlay can be used to brand a video or add a label in the form of text.

thumbnail

string

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_format

string

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

Default: png

mp4_access

boolean

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

Default: false

per_title_encoding

boolean

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

metadata

object

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

process_low_resolution_input

boolean

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
response
cURL
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"
}'
response
{
"asset_id": "5fce1951df953f1e913f4604",
"progress": 0,
"created_at": 1607342417707,
"status": "queued",
"tag": "",
"input": {
"transformations": {
"resolution": [],
"thumbnail": [
"auto"
],
"format": "hls",
"video_codec": "libx264",
"audio_codec": "aac",
"thumbnail_format": "png",
"mp4_access": false
},
"source_url": "https://gumlet.sgp1.digitaloceanspaces.com/video/sample_1.mp4"
},
"output": {
"status_url": "https://api.gumlet.com/video/v1/status/5fce1951df953f1e913f4604",
"playback_url": "https://video.gumlet.io/5f462c1561cf8a766464ffc4/5fce1951df953f1e913f4604/1.m3u8",
"thumbnail_url": [
"https://video.gumlet.io/5f462c1561cf8a766464ffc4/5fce1951df953f1e913f4604/thumbnail-1-0.png"
]
}
}

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

Parameter

Type

Description

asset_id

string

An asset id for the previously created asset.

cURL
response
cURL
curl -L -X GET 'https://api.gumlet.com/v1/video/assets/5fce1951df953f1e913f4604' \
-H 'Authorization: Bearer <YOUR_API_KEY>'
response
{
"asset_id": "5fce1951df953f1e913f4604",
"progress": 100,
"created_at": 1607342417707,
"status": "ready",
"tag": "",
"input": {
"transformations": {
"resolution": [],
"thumbnail": [
"auto"
],
"format": "hls",
"video_codec": "libx264",
"audio_codec": "aac",
"thumbnail_format": "png",
"mp4_access": false
},
"source_url": "https://gumlet.sgp1.digitaloceanspaces.com/video/sample_1.mp4",
"size": 15240078,
"duration": 20.32,
"aspect_ratio": "16:9",
"fps": "30000/1001",
"width": 1920,
"height": 1080
},
"output": {
"status_url": "https://api.gumlet.com/video/v1/status/5fce1951df953f1e913f4604",
"playback_url": "https://video.gumlet.io/5f462c1561cf8a766464ffc4/5fce1951df953f1e913f4604/1.m3u8",
"thumbnail_url": [
"https://video.gumlet.io/5f462c1561cf8a766464ffc4/5fce1951df953f1e913f4604/thumbnail-1-0.png"
],
"storage_bytes": 54149281
},
"processed_at": 1607342550068
}

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

Parameter

Type

Description

source_id

string

Gumlet video source id.

Query Parameters

Parameter

Type

Description

status

string

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

tag

string

Input tag on the basis of which assets need to be filtered.

offset

integer

Offset value for a paginated list of assets.

size

integer

Page size for the paginated list.

Default: 10

cURL
response
cURL
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>'
response
{
"all_assets": [
{
"asset_id": "5fce1951df953f1e913f4604",
"progress": 100,
"created_at": 1607342417707,
"status": "ready",
"tag": "Gumlet",
"input": {
"transformations": {
"resolution": [],
"thumbnail": [
"auto"
],
"format": "hls",
"video_codec": "libx264",
"audio_codec": "aac",
"thumbnail_format": "png",
"mp4_access": false
},
"source_url": "https://gumlet.sgp1.digitaloceanspaces.com/video/sample_1.mp4",
"size": 15240078,
"duration": 20.32,
"aspect_ratio": "16:9",
"fps": "30000/1001",
"width": 1920,
"height": 1080
},
"output": {
"status_url": "https://api.gumlet.com/video/v1/status/5fce1951df953f1e913f4604",
"playback_url": "https://video.gumlet.io/5f462c1561cf8a766464ffc4/5fce1951df953f1e913f4604/1.m3u8",
"thumbnail_url": [
"https://video.gumlet.io/5f462c1561cf8a766464ffc4/5fce1951df953f1e913f4604/thumbnail-1-0.png"
],
"storage_bytes": 54149281
},
"processed_at": 1607342550068
}
],
"total_asset_count": 21,
"current_offset": 21
}

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

Parameter

Type

Description

asset_id

string

An asset id for the previously created asset.

cURL
response
cURL
curl -L -X DELETE 'http://api.gumlet.com/v1/video/assets/5f48b955115462793462ab03' \
-H 'authorization: Bearer <YOUR_API_KEY>'
response
{}