Skip to main content
videas.comCreate ticketGo to app

How uploads work

A beginner-friendly overview of uploading media to Videas — resumable uploads, chunking, size limits, and how to handle large video files.

Updated 28 Aug 2026uploaduploadstusconceptslarge-files

New to Videas? This page explains, from scratch, how you get a file (usually a video) into the platform — and how to do it reliably even for large files. Once you understand the model, pick your path: the SDK (recommended) or the REST API.

What “uploading” means here

You upload a file into a workspace. Videas stores it and creates an asset (a video, audio, image or document) that you can then play, embed and manage through the API. Every upload is tied to your organization via your API key.

The same asset shows up in the Mediasbox media library, inside the folder you named: what your integration drops off, your client finds and files without writing a line of code.

Uploads are resumable and chunked

Videos are big, and networks are unreliable — so Videas doesn’t take the whole file in one shot. It uses the resumable TUS protocol, which works in two moves:

  1. Create an upload session — you announce the file (its name and total size). Videas replies with a URL to send the bytes to.
  2. Send the bytes in chunks — you transfer the file in pieces, one after another. If a chunk fails, you retry just that chunk instead of restarting.

You don’t send the whole file in a single request: each chunk must stay under the per-chunk limit (see below). Splitting a large file into chunks is the core idea that makes big uploads work.

Good news: the official SDKs do all of this for you — session creation, chunking, offsets, retries. You call one function. Only reach for the raw protocol if you can’t use an SDK.

Limits you should know

Limit Value What it means
Per-chunk size 50 MiB The maximum size of a single transfer request. Larger files must be split into several chunks (the SDK uses 32 MiB by default).
Total file size 10 GiB The maximum size of one uploaded file.
Session lifetime 24 hours An upload session expires if not completed in time; start a fresh one after that.

Exceeding the per-chunk limit returns an error like Chunk too large: … exceeds maximum 52428800 bytes — that’s the signal to send smaller chunks (the SDK never hits this).

After the upload: processing

As soon as the session is created you get an asset_uid — the id of the asset being created — even before the bytes finish transferring. Videos are then processed asynchronously (transcoding, thumbnails…), so the asset isn’t immediately playable. Transcoding produces an adaptive-bitrate HLS stream served over a CDN — that is what Video hosting covers, and what you get back at playback time.

Poll the asset until it’s ready:

GET /api/external/v1/assets/{asset_uid}/   →   { "status": "ready", … }

Statuses move from processing to ready (or error). Don’t try to play or embed an asset until it reports ready.

Handling large files well

  • Prefer the SDK. It streams the file in chunks so you never hold the whole thing in memory, tracks progress, and surfaces clear errors.
  • Show progress. For multi-hundred-MB or multi-GB files, give users a progress bar (the SDKs expose a progress callback).
  • Don’t buffer huge files in memory if you can avoid it — read/stream from disk. (The raw API lets you send any chunk slice; the SDK handles this.)
  • Expect to resume, not restart. With chunks, a dropped connection only costs the current chunk, not the whole file.

Choose your path

Next steps