Files make up the foundation of operating with Cloudglue. Files represent a video or audio file that you want to operate on. Once you upload a file, you can use it anywhere in the Cloudglue platform, whether it may be for on-demand operations like transcribing or for use in collections like entities collections. We do not use your files for any purpose other than to provide you with the service you signed up for.

​
Working with Files

​
Uploading Files

​
Web App

The Cloudglue web app allows you to upload files by dragging and dropping them into the web app or by selecting them from your file system. Upload File Uploader Dialog Note: Local uploads are best for files under 250 MB. For larger files, use a data connector.

​
API

You can also upload files via our Files API.
Example
curl --request POST \
  --url https://api.cloudglue.dev/v1/files \
  --header 'Authorization: Bearer cg-YOUR_API_KEY' \
  --header 'Content-Type: multipart/form-data' \
  --form 'metadata={}' \
  --form file=@file.mp4

​
SDKs

You can also use our SDKs to upload files to Cloudglue.
Example
import { CloudGlue } from '@aviaryhq/cloudglue-js';

const cloudGlue = new CloudGlue({
apiKey: 'cg-YOUR_API_KEY',
});

const file = await cloudGlue.files.uploadFile({
  file: new File([...videoData], 'video.mp4'),
  metadata: {},
});

console.log(file);

​
File Metadata

When uploading a file, you can pass in metadata. This metadata is for your own reference. You can use this to store your own custom data, such as identifiers or names from your own system. When you retrieve a file, the metadata is included in the response.
Example
const file = await cloudGlue.files.uploadFile({
  file: new File([...videoData], 'video.mp4'),
  metadata: {
    my_own_id: '12345687890',
    type: 'Sales Footage',
  },
});

const file = await cloudGlue.files.getFile(file.id);

console.log(file);
Response
  {
    ...,
    "metadata": {
      "my_own_id": "12345687890",
      "type": "Sales Footage"
    }
  }

​
File Status

Cloudglue is inherently asynchronous. We use the file status to indicate the current status of the file. The possible values are:
  • pending - The file is pending and has not been processed yet.
  • processing - The file is being processed.
  • completed - The file has been processed successfully.
  • failed - The file failed to process.
You can check the status of a file by calling the getFile method.
Example
const file = await cloudGlue.files.getFile(file.id);

console.log(file.status);
Response
'pending' | 'processing' | 'completed' | 'failed';
Webhooks
To listen for file status updates asynchronously, you can use our webhooks. You can provide an endpoint to listen to the following file events:
  • file.job.processing - When a file is being processed.
  • file.job.completed - When a file has been processed successfully.
  • file.job.failed - When a file has failed to process.
  • file.job.deleted - When a file is deleted.

​
File Limits & Requirements

​
Size Limits

  • Maximum file size: 2 GB per file
  • Local upload limit: 250 MB for uploads via web app or files API
    • Larger local uploads may fail or lead to slow processing times
    • For files larger than 250 MB, use a data connector such as AWS S3

​
Duration Limits

  • Minimum duration: 2 seconds
  • Maximum duration: 2 hours
  • Files longer than 2 hours must be split into multiple parts before uploading
  • Each part must still respect the 2 GB size limit

​
Upload Limits

We do not charge you for the storage of your files. However, we do have some limits in place to prevent abuse. To see the limits, please see the Rate Limits page.

​
Higher Limits

If you need larger file sizes or expect to upload many large files, contact us to discuss custom limits.

​
Supported File Types

Cloudglue supports the following file types:
  • application/octet-stream
  • video/mp4
  • video/quicktime
  • video/avi
  • video/webm
Don’t see your file type? Contact us about it.

​
Optimal File Formatting

To ensure fast processing and reliable playback, uploaded videos should follow these industry-standard encoding parameters. We will start rejecting non-standard inputs in the future:
ParameterRecommended ValueNotes
ContainerMP4 (.mp4)Use MP4 container with moov atom at the start (use -movflags +faststart option when encoding)
Video CodecH.264 (AVC)H.264 is widely supported. Other codecs (HEVC/ProRes/etc.) may be transcoded and could be rejected in the future
Resolution≤1080p/2K (≤2048×2048)Higher resolutions increase processing time and may exceed file-size limits
Audio CodecAACNon-AAC audio will be transcoded and may be rejected
Audio ChannelsMono or stereoMulti-channel audio (5.1, 7.1, etc.) will be down-mixed

​
Transcoding with ffmpeg to ideal video format

Use ffmpeg to convert your source video into a supported format: 
ffmpeg -i input_video.ext \
       -c:v libx264 \
       -vf "scale=w=min(iw\,1920):h=-2" \
       -c:a aac -b:a 192k -ac 2 \
       -movflags +faststart \
       output.mp4
This command:
  • Uses H.264 video codec
  • Limits width to ≤1920px while maintaining aspect ratio
  • Encodes stereo AAC audio at 192k bitrate
  • Puts MP4 metadata at start for faster streaming

​
Checking Video Specifications

Use this script to check if your video meets the recommended specifications: 
#!/bin/bash
# Usage: ./check-video.sh <file>
FILE="$1"

# Extract video properties: codec, width, height
read -r vcodec width height <<<$(ffprobe -v error -select_streams v:0 \
    -show_entries stream=codec_name,width,height \
    -of default=noprint_wrappers=1:nokey=1 "$FILE")

# Extract audio properties: codec, channels
read -r acodec channels <<<$(ffprobe -v error -select_streams a:0 \
    -show_entries stream=codec_name,channels \
    -of default=noprint_wrappers=1:nokey=1 "$FILE")

# Flag if any property falls outside the recommended specs
needs_transcode=0
if [[ "$vcodec" != "h264" ]] || [[ "$width" -gt 2048 ]] || [[ "$height" -gt 2048 ]]; then
    needs_transcode=1
fi
if [[ "$acodec" != "aac" ]] || [[ "$channels" -gt 2 ]]; then
    needs_transcode=1
fi

if [[ $needs_transcode -eq 1 ]]; then
    echo "This file does not meet the recommended specs and should be transcoded."
else
    echo "This file meets the recommended specs."
fi

​
Splitting Large Videos

If your video is longer than 2 hours or larger than 2 GB, split it into compliant chunks: 
# Split into 90-minute segments without re-encoding
ffmpeg -i long_video.mp4 -map 0 -c copy -f segment \
       -segment_time 01:30:00 -reset_timestamps 1 \
       part_%03d.mp4
To check duration and size before splitting: 
ffprobe -i input.mp4 -hide_banner -v error \
        -show_entries format=duration,size \
        -of default=noprint_wrappers=1:nokey=1

​
Best Practices Summary

  • For quick experiments: Use local uploads for files under 250 MB
  • For larger files: Set up a data connector such as AWS S3
  • Before uploading: Ensure files are 2 seconds to 2 hours duration and ≤2 GB
  • For optimal performance: Use MP4 with H.264 video, AAC audio, ≤1080p resolution
  • For long videos: Split into chunks using ffmpeg and track parts with metadata
  • Always check: Use ffprobe to verify file specifications before upload
For questions about custom limits or larger file requirements, contact our support team.