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
{}

Text Overlay

Transformation Options

Last updated 5 days ago

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`, and`MPEG-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`

Video APIs

Authentication

`POST` Create Asset

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

Body Parameters

`GET` Get Asset Status

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

Path Parameters

`GET` Filter Assets

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

Path Parameters

Query Parameters

`DELETE` Delete Asset

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

Path Parameters