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, mkv, 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
text
optional
string
To add text overlay on the asset. The text string can be specified with this parameter.
text_position
optional
string
Position of the overlay text 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
text_color
optional
string
Color of the overlay text can be specified with this parameter. Default: black
text_font
optional
string
Font type of the overlay text can be specified with this parameter. Default font is is sans-serif but you can specify any web-safe fonts to use here.
text_font_size
optional
integer
Font size in pixels of the overlay text can be specified with this parameter. Default: 16
text_opacity
optional
number
Overlay text opacity can be specified with this parameter. Value can be between 0.0 and 1.0 where 0.0 being completely transparent and 1.0 being completely opaque. Default: 1.0
text_box
optional
boolean
To draw a rectangular box over overlayed text. Value can be true or false. Default: false
text_box_color
optional
string
Background color for the rectangular box over overlayed text can be specified with this parameter. Default: white
text_box_opacity
optional
number
Opacity for the rectangular box over overlayed text can be specified with this parameter. Value can be between 0.0 and 1.0 where 0.0 being completely transparent and 1.0 being completely opaque. Default: 1.0
text_box_border
optional
integer
Padding (in pixels) between the rectangular box and overlayed text can be controlled with this parameter. Default: 0
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 H.264, H.265, and VP9.
Default: H.264
ac
optional
string
Specify audio codec for the asset. The options can be one of AAC, OPUS, VORBIS, and MP3.
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
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 4 weeks 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
