Direct Upload

Upload files directly to Gumlet

Using Dashboard

Upload your videos directly from the dashboard using this guide

Using REST APIs (Direct Upload)

Prefer the official SDKs when available:

Node.js / TypeScript SDK — npm install @gumlet/nodejs-sdk
Python SDK — pip install gumlet

1. Create an authenticated Gumlet URL

The first step is creating a new Direct Upload Asset with Asset Parameters per your requirements. The Gumlet API will return an authenticated URL that you can use directly, and an asset ID specific to that Direct Upload Asset so you can check the status later via the API or in Gumlet Dashboard.

import Gumlet from '@gumlet/nodejs-sdk';

const client = new Gumlet({
  apiKey: process.env['API_KEY'],
});

const videoAsset = await client.videoAssets.upload({
  collection_id: '<your workspace id>',
  format: 'ABR',
});

console.log(videoAsset.upload_url, videoAsset.asset_id);

import os

from gumlet import Gumlet

client = Gumlet(
    api_key=os.environ.get("API_KEY"),
)

video_asset = client.video_assets.upload(
    collection_id="<your workspace id>",
    format="ABR",
)

print(video_asset.upload_url, video_asset.asset_id)

curl -L -X POST 'https://api.gumlet.com/v1/video/assets/upload' \
-H 'Authorization: Bearer <YOUR_API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
    "collection_id": "<your workspace id>",
    "format": "ABR"
}'

2. Use the URL to upload a file

Once you have got upload_url from the previous step, make a PUT request that includes the file in the body. This upload goes to the pre-signed URL (not through the Gumlet SDK client).

import { readFile } from 'node:fs/promises';

const uploadUrl = '<upload_url>';
const file = await readFile('video.mp4');

const response = await fetch(uploadUrl, {
  method: 'PUT',
  headers: {
    'Content-Type': 'video/mp4',
  },
  body: file,
});

if (!response.ok) {
  throw new Error(`Upload failed: ${response.status} ${response.statusText}`);
}

console.log('Upload complete');

import requests

upload_url = "<upload_url>"

with open("video.mp4", "rb") as video_file:
    response = requests.put(
        upload_url,
        headers={"Content-Type": "video/mp4"},
        data=video_file,
    )

response.raise_for_status()
print("Upload complete")

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

On successful upload, the new assets will be available in the Gumlet Dashboard.

3. Access uploaded video

Access your uploaded video using the Video Asset Status API. You will receive the original_download_url parameter.

const videoAsset = await client.videoAssets.retrieveDetails('<asset_id>');
console.log(videoAsset);

video_asset = client.video_assets.retrieve_details(
    asset_id="<asset_id>",
)
print(video_asset)

curl -L -X GET 'https://api.gumlet.com/v1/video/assets/<asset_id>' \
-H 'Authorization: Bearer <YOUR_API_KEY>'

By default, Gumlet will keep your original videos in its storage. If you don't want your original video to be stored on Gumlet storage then, you can add keep_original parameter with value false in Create Asset API and Gumlet will delete your original video after processing.

Using REST APIs (Multipart Upload)

Use multipart upload for large files. Create the asset first, split the video into parts of at least 5MB (unless the video is smaller than 5MB), upload each part to a pre-signed URL, then complete the upload.

1. Create asset for upload

Create a new Upload Asset with Asset Parameters per your requirements.

const videoAsset = await client.videoAssets.upload({
  collection_id: '<your workspace id>',
  format: 'ABR',
});

const assetId = videoAsset.asset_id;

video_asset = client.video_assets.upload(
    collection_id="<your workspace id>",
    format="ABR",
)

asset_id = video_asset.asset_id

curl -L -X POST 'https://api.gumlet.com/v1/video/assets/upload' \
-H 'Authorization: Bearer <YOUR_API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
    "collection_id": "<your workspace id>",
    "format": "ABR"
}'

2. Create parts of the original video

Create multiple parts of your video. Make sure each part is at least 5MB (unless the video is less than 5MB itself, then it will be only 1 part).

3. Sign part and upload

Get a pre-signed upload URL for each part using the sign part API call. Use asset_id received from the create upload asset call.

import { readFile } from 'node:fs/promises';

const partNumber = '1';
const signed = await client.multipartUpload.retrievePartURL(partNumber, {
  asset_id: assetId,
});

const partData = await readFile('part-1.bin');
const uploadResponse = await fetch(signed.part_upload_url, {
  method: 'PUT',
  body: partData,
});

if (!uploadResponse.ok) {
  throw new Error(`Part upload failed: ${uploadResponse.status}`);
}

const etag = uploadResponse.headers.get('etag');
// Store PartNumber + ETag for every part

import requests

part_number = "1"
signed = client.multipart_upload.retrieve_part_url(
    asset_id=asset_id,
    part_number=part_number,
)

with open("part-1.bin", "rb") as part_file:
    upload_response = requests.put(signed.part_upload_url, data=part_file)

upload_response.raise_for_status()
etag = upload_response.headers["ETag"]
# Store PartNumber + ETag for every part

curl -L -X GET 'https://api.gumlet.com/v1/video/assets/{asset_id}/multipartupload/{part_number}/sign' \
-H 'Authorization: Bearer <YOUR_API_KEY>'

Upload the part using the part_upload_url:

curl -v -X PUT -T part_binary_data '<part_upload_url>'

Store the ETag value of the response header for each part.

4. Complete multipart upload

Once you upload all the parts using their part_upload_url, complete the multipart upload using this API call. Send an array of PartNumber and ETag values received while uploading each part.

await client.multipartUpload.complete(assetId, {
  parts: [
    { PartNumber: 1, ETag: '1ae165be27bf32b6430c150620ee9b8f' },
    { PartNumber: 2, ETag: '52e124ba4c6f32b31dac23e6033e9c4d' },
  ],
});

client.multipart_upload.complete(
    asset_id=asset_id,
    parts=[
        {"part_number": 1, "e_tag": "1ae165be27bf32b6430c150620ee9b8f"},
        {"part_number": 2, "e_tag": "52e124ba4c6f32b31dac23e6033e9c4d"},
    ],
)

curl -L -X POST 'https://api.gumlet.com/v1/video/assets/{asset_id}/multipartupload/complete' \
-H 'Authorization: Bearer <YOUR_API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
    "parts": [
        {"PartNumber": 1, "ETag": "1ae165be27bf32b6430c150620ee9b8f"},
        {"PartNumber": 2, "ETag": "52e124ba4c6f32b31dac23e6033e9c4d"}
    ]
}'

Using REST API (Subtitle Upload)

1. Upload .srt file

First create signed subtitle upload URLs with the Upload Subtitle API. Then PUT each .srt / .vtt file to the returned URL. Finally call the complete API so Gumlet attaches the subtitles to the asset.

import { readFile } from 'node:fs/promises';

const subtitleUpload = await client.subtitleUpload.upload(assetId, {
  language_codes: ['en'],
});

const signedUrl = subtitleUpload.signed_urls?.[0]?.upload_url;
const subtitleFile = await readFile('subtitles.en.srt');

const putResponse = await fetch(signedUrl, {
  method: 'PUT',
  body: subtitleFile,
});

if (!putResponse.ok) {
  throw new Error(`Subtitle upload failed: ${putResponse.status}`);
}

await client.subtitleUpload.complete(assetId, {
  upload_responses: [{ language_code: 'en', uploaded: true }],
});

import requests

subtitle_upload = client.subtitle_upload.upload(
    asset_id=asset_id,
    language_codes=["en"],
)

upload_url = subtitle_upload.signed_urls[0].upload_url

with open("subtitles.en.srt", "rb") as subtitle_file:
    put_response = requests.put(upload_url, data=subtitle_file)

put_response.raise_for_status()

client.subtitle_upload.complete(
    asset_id=asset_id,
    upload_responses=[{"language_code": "en", "uploaded": True}],
)

# 1. Request signed upload URLs
curl -L -X POST 'https://api.gumlet.com/v1/video/assets/<asset_id>/subtitle/upload' \
-H 'Authorization: Bearer <YOUR_API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
    "language_codes": ["en"]
}'

# 2. Upload the subtitle file
curl --location --request PUT '<upload_url>' \
--data-binary '@subtitles.en.srt'

# 3. Complete subtitle upload
curl -L -X POST 'https://api.gumlet.com/v1/video/assets/<asset_id>/subtitle/upload/event' \
-H 'Authorization: Bearer <YOUR_API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
    "upload_responses": [
        {"language_code": "en", "uploaded": true}
    ]
}'

On success you will get 200 OK status.

API Keys

Replace Video