Video APIs

Complete API reference for Gumlet video processing and delivery service
Currently, these APIs are in private beta, please contact support@gumlet.com for enabling them.
post
Create Asset
https://api.gumlet.com/v1/video/process
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.
Request
Response
Request
Headers
authorization
required
string
'Bearer <YOUR_API_KEY>'
Body Parameters
input
required
string
URL or web address of a file that Gumlet should download to create a new asset.
sourceId
required
string
Gumlet video source Id.
format
required
string
Transcode and deliver the asset in the requested format. The options can be one of mp4, HLS, MPEG-DASH, mov, mkv, avi and webm
width
optional
number
Required width of the transformed asset. Specified values greater than the original asset width will be ignored.
height
optional
number
Required height of transformed asset. Specified values greater than the original asset height will be ignored.
resolution
optional
string
Required resolutions of the transformed asset in case of HLS or MPEG-DASH delivery format. Can be a comma-separated string out of the following values: 120p, 240p, 360p, 480p, 540p, 720p, 1080p, and 1440p. Width of the transformed asset will be forced to input (asset) aspect ratio.
crop
optional
string
Extract a given width and height out of the original asset. The original proportions are retained and so is the size of the graphics. Used together with x and y coordinates for specifying the section to crop.
Format: x,y,height,width
pad
optional
string
Add padding with specified color (Default: Black) in asset.
Format: top,right,bottom,left,color
overlay_url
optional
string
To add an image overlay on the asset. URL of the image can be specified with this parameter.
overlay_size
optional
string
Width and height (in pixels) of overlay image can be specified using this parameter with width,height format. 
Default: actual width and height of the overlay image.
overlay_position
optional
string
Position of the overlay image on the asset can be specified using this parameter. Values can be x and y coordinates in x,y format or one of the following values:top, topleft, left, bottomleft, bottom, bottomright, right, topright, and center. Default: bottomright
ar
optional
string
Change aspect ratio of the asset in format x:y.
so
optional
number
Start offset in seconds from which asset will be trimmed.
eo
optional
number
End offset in seconds till asset to be trimmed.
du
optional
number
Trim asset with start offset (so) parameter. The asset will be trimmed from start offset timestamp till duration in seconds provided using this parameter.
offset
optional
string
Trim asset using a combination of start and end offset in seconds (float value), separated by a comma.
For example: "30.0,50.0" (trim video from 30 to 50 seconds.)
vc
optional
string
Specify video codec for the asset. The options can be one of libx264 and libx265.
Default: libx264
ac
optional
string
Specify audio codec for the asset. The options can be one of aac, mp3 and opus.
Default: aac
fps
optional
integer
Change FPS (Frames-Per-Second) of the asset. If specified fps greater than source fps then frames will be duplicated. In the case of smaller specified fps than source fps, frames will be removed.
Default: same as source
maxres
optional
string
The name of the streaming profile to apply to HLS adaptive bitrate streaming. The options can be one of SD, HD, FHD and UHD.
Default: HD
thumbnail
optional
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
optional
string
Specify the thumbnail image format. Supported formats are jpeg, jpg, png and webp.
Default: png
Response
200: OK
Cake successfully retrieved.
{
    "assetId": "5f4c9d9a115462105e62ac6d",
    "progress": 0,
    "createdAt": 1598870315007,
    "status": "queued",
    "tag": "",
    "input": {
        "transformations": {
            "format": "hls",
            "thumbnail": "auto",
            "thumbnailFormat": "png"
        },
        "sourceUrl": "https://gumlet.sgp1.digitaloceanspaces.com/video/sample.mp4"
    },
    "output": {
        "statusUrl": "https://api.gumlet.com/video/v1/status/5f4c9d9a115462105e62ac6d",
        "playbackUrl": "https://video.gumlet.io/5f462c1561cf8a766464ffc4/5f4c9d9a115462105e62ac6d/1.m3u8",
        "thumbnailUrl": "https://video.gumlet.io/5f462c1561cf8a766464ffc4/5f4c9d9a115462105e62ac6d/0.png"
    }
}
Example cURL request is given below.
curl -L -X POST 'https://api.gumlet.com/video/v1/process' \
-H 'authorization: Bearer <YOUR_API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
    "input":"https://gumlet.sgp1.digitaloceanspaces.com/video/sample.mp4",
    "sourceId":"5f462c1561cf8a766464ffc5",
    "format":"hls",
}'
get
Get Asset Status
https://api.gumlet.com/v1/video/status/:assetId
This endpoint retrieves the details of an asset that has previously been created. Given the unique asset ID that was returned from your previous request, and Gumlet will return the corresponding asset status.
Request
Response
Request
Path Parameters
assetId
required
string
An asset id for the previously created asset.
Headers
authorization
required
string
'Bearer YOUR_API_KEY'
Response
200: OK
{
    "assetId": "5f4c9d9a115462105e62ac6d",
    "progress": 13,
    "createdAt": 1598870315007,
    "status": "processing",
    "tag": "",
    "input": {
        "transformations": {
            "format": "hls",
            "thumbnail": "auto",
            "thumbnailFormat": "png"
        },
        "sourceUrl": "https://gumlet.sgp1.digitaloceanspaces.com/video/sample.mp4",
        "size": 89056456,
        "duration": 29.503333,
        "aspectRatio": "N/A",
        "fps": "24000/1001",
        "width": 3840,
        "height": 2160
    },
    "output": {
        "statusUrl": "https://api.gumlet.com/video/v1/status/5f4c9d9a115462105e62ac6d",
        "playbackUrl": "https://video.gumlet.io/5f462c1561cf8a766464ffc4/5f4c9d9a115462105e62ac6d/1.m3u8",
        "thumbnailUrl": "https://video.gumlet.io/5f462c1561cf8a766464ffc4/5f4c9d9a115462105e62ac6d/0.png"
    }
}
400: Bad Request
{}
Example cURL request is given below.
curl -L -X GET 'https://api.gumlet.com/video/v1/status/5f4c9d9a115462105e62ac6d' \  
-H 'authorization: Bearer <YOUR_API_KEY>'
get
List Assets
https://api.gumlet.com/v1/video/list/:sourceId
This endpoint retrieves the details of all assets that have previously been created. Given the unique sourceId, Gumlet will return the corresponding paginated list of asset status.
Request
Response
Request
Path Parameters
sourceId
required
string
Gumlet video source id.''
Headers
authorization
required
string
'Bearer <YOUR_API_KEY>'
Query Parameters
offset
optional
string
Offset value for a paginated list of assets. Can be zero for the first time andcurrentOffsetvalue received from the last request afterward.
status
optional
string
To filter assets on the basis of its 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.
size
optional
int
Page size for the paginated list. Default: 10
Response
200: OK
{
    "allAssets": [
        {
            "assetId": "5f463b191b3c9762c20c8f9b",
            "progress": 100,
            "createdAt": "2020-08-26T10:36:09.527Z",
            "status": "ready",
            "tag": "",
            "input": {
                "transformations": {
                    "format": "mp4",
                    "thumbnail": "30%",
                    "thumbnailFormat": "jpg"
                },
                "sourceUrl": "https://example.com/abc.mp4",
                "size": 17839845,
                "duration": 30.526667,
                "aspectRatio": "16:9",
                "fps": "30/1",
                "width": 1920,
                "height": 1080
            },
            "output": {
                "statusUrl": "https://api.gumlet.com/video/v1/status/5f463b191b3c9762c20c8f9b",
                "playbackUrl": "https://video.gumlet.io/5f462c1561cf8a766464ffc4/5f463b191b3c9762c20c8f9b/0.mp4",
                "thumbnailUrl": "https://video.gumlet.io/5f462c1561cf8a766464ffc4/5f463b191b3c9762c20c8f9b/2.jpg",
                "storageBytes": 3736150
            },
            "processedAt": "2020-08-26T10:36:34.483Z"
        }
    ],
    "totalAssetCount": 10,
    "currentOffset": 1
}
400: Bad Request
{}
Example cURL request is given below.
curl -L -X GET 'https://api.gumlet.com/video/v1/list/5f462c1561cf8a766464ffc5?offset=0&size=1&status=ready' \  
-H 'authorization: Bearer <YOUR_API_KEY>'
delete
Delete Asset
http://api.gumlet.com/v1/video/:assetId
This endpoint removes an asset given its unique asset id. The asset will be removed from storage as well, associated URLs will be inaccessible.
Request
Response
Request
Path Parameters
assetId
required
An asset id for the previously created asset.
Headers
authorization
required
string
'Bearer <YOUR_API_KEY>'
Response
200: OK
​
400: Bad Request
{}
Example cURL request is given below.
curl -L -X DELETE 'http://api.gumlet.com/video/v1/5f48b955115462793462ab03' \  
-H 'authorization: Bearer <YOUR_API_KEY>'
Text Overlay
Next - 📖 Reference
Source APIs
Last updated 2 days ago
Video APIs

postCreate Asset

getGet Asset Status

getList Assets

deleteDelete Asset

post
Create Asset

get
Get Asset Status

get
List Assets

delete
Delete Asset
