Chunked Video Upload Tutorial: 50-200MB Parts Explained

The Node.js SDK article showed that client.uploadVideo() handles chunking for you, one call, done. That's the right answer if you're in Node and want the SDK's convenience. It's also not useful if you're on a different stack, or you actually want to understand what that one call is doing underneath. This is the raw mechanics: the actual endpoints, the actual part-splitting math, and what AIOZ Stream's docs do and don't tell you about handling a failure mid-upload.

TL;DR:

• AIOZ Stream's chunked upload uses three calls: create the video object, upload one or more parts (each 50-200MB), then call complete to trigger transcoding.
• Each part upload needs a zero-based index, an MD5 hash of that part's bytes, the raw chunk as file, and a Content-Range header stating the byte range within the full file.
• AIOZ's documentation doesn't specify retry or resume behavior for a failed part, no offset-check endpoint, no documented behavior for re-uploading an already-received index.
• The tus resumable-upload protocol, a well-specified alternative used elsewhere in the industry, solves this with a HEAD request returning an Upload-Offset header, a mechanism AIOZ Stream's docs don't describe having.
• If you're already in Node, use the SDK's uploadVideo() or the three explicit SDK calls instead of reimplementing this loop by hand, this article is for every other stack, or for understanding what's happening underneath either SDK path.

Why chunk a video upload at all

A single large POST request carries real risk that splitting into parts avoids. Video files routinely run into multiple gigabytes, and a connection interruption partway through a monolithic upload means restarting the entire transfer from byte zero, not just the part that failed. Chunking bounds the blast radius of a failure to whatever a single part represents, and it gives a client the option to parallelize parts, retry one specific failed part, or report granular progress, none of which a single unbroken request stream can offer. AIOZ Stream's documented part-size range, 50MB to 200MB per chunk, sits in a reasonable middle ground: small enough that a failed part doesn't cost much re-upload time, large enough that a multi-gigabyte file doesn't turn into hundreds of separate HTTP round trips. For scale, Amazon S3's own multipart upload, the pattern most developers have already encountered, allows parts from 5MB up to 5GB, with a maximum of 10,000 parts, "no minimum size limit on the last part," per AWS's own documentation. AIOZ's range is narrower and doesn't publish an equivalent explicit note about the final part, worth keeping in mind since it means treating the last-chunk behavior as a reasonable inference rather than a documented guarantee.

The three-endpoint sequence

Three calls, in order, do the whole job. First, create the video object with a metadata-only POST to https://api.aiozstream.network/api/media/create, sending at minimum a title; the response returns the video's id, which every subsequent call needs. Second, upload each part with a POST to https://api.aiozstream.network/api/media/:video_id/part, repeated once per chunk. Third, once every part has uploaded successfully, a single GET to https://api.aiozstream.network/api/media/:video_id/complete tells AIOZ Stream the upload is done and transcoding can start. That completion call matters more than it looks: skip it, and a fully-uploaded set of parts just sits there, unprocessed, because nothing else in the sequence tells the platform the file is whole.

Building the chunking loop by hand

The part-upload call has four pieces that all have to line up correctly. The index parameter is the part's zero-based position in the sequence, the first chunk is index 0, the second is 1, and so on. The hash parameter is the MD5 hash of that specific chunk's bytes, not the whole file, computed before sending so the server can verify the part arrived intact. The file parameter is the raw chunk data itself, sliced from the source file at a boundary somewhere between 50MB and 200MB. And the Content-Range header states exactly where this chunk sits in the full file, in the standard bytes {start}-{end}/{total} format, for example Content-Range: bytes 0-104857599/524288000 for a 100MB first chunk out of a 500MB file. A minimal loop in pseudocode looks like this: read the file's total size, pick a chunk size inside the documented range, say 100MB, compute how many chunks that produces, then for each chunk in order, read that byte range from disk, hash it, and POST it with the matching index and Content-Range header before moving to the next one. Nothing in the documented process requires chunks to be a uniform size, only that each individual part fall within 50-200MB. That leaves an open question the docs don't directly answer: what happens to a final remainder chunk smaller than 50MB, the minimum for every other part. S3's own docs handle this by explicitly exempting the last part from the minimum-size rule; AIOZ Stream's docs don't make an equivalent statement either way. The defensible approach given that silence is to keep every part, including the last, within the documented 50-200MB range wherever the file size allows it, and treat a sub-50MB final remainder as untested territory worth a real test upload before relying on it in production, rather than assuming S3's convention applies here just because it's the more familiar pattern.

What the docs don't specify

Three real gaps are worth planning around rather than discovering during an outage. AIOZ's public documentation doesn't describe what happens if a part upload fails partway through, no documented retry guidance beyond the implicit assumption that a client will simply try that same index again. It doesn't specify whether re-uploading an already-successfully-received index overwrites the original or gets rejected, so treat that as unverified rather than assuming either behavior. And there's no documented way to ask the server which parts it has already received for a given video, no equivalent of a status check before resuming an interrupted session. Contrast that with tus, an open resumable-upload protocol used elsewhere in the industry: a tus-compliant server responds to a HEAD request with an Upload-Offset header telling the client exactly how many bytes it already has, so a client that lost its connection can query that offset and resume precisely instead of guessing. AIOZ Stream's docs don't describe an equivalent mechanism, which means the safe engineering choice is keeping your own local record, which indexes have confirmed successfully, so a resumed session after a crash re-sends only what's actually missing rather than either skipping a part that failed silently or re-sending everything from scratch.

When to just use the SDK instead

If the project is already in Node, this entire loop is a solved problem, not a new one to build. The Node.js SDK article covers both client.uploadVideo(), a single call that handles chunking, upload, and completion together, and the three-call explicit version, video.create(), video.uploadPart(), and video.uploadVideoComplete(), for when you want a hook between the upload finishing and marking it complete. Reimplementing the raw part-splitting logic above only makes sense outside Node, or when a specific need, custom retry logic the SDK doesn't expose, a different runtime entirely, requires working against the raw endpoints directly. AIOZ also maintains an official Go client, so a Go backend has the same choice Node does, a maintained wrapper instead of hand-rolled part-splitting. Python, PHP, or any other stack without an official client is exactly the case this article is for: the create/part/complete sequence above, the index and hash and Content-Range requirements, is the same regardless of language, since it's the raw HTTP contract every SDK is ultimately built on top of.

Frequently Asked Questions

What's the allowed chunk size for AIOZ Stream's part upload?
50MB to 200MB per part, per AIOZ Stream's API documentation. Parts don't need to be a uniform size within that range.

Do I need to create the video object before uploading any parts?
Yes. The create call returns the video ID every subsequent part-upload and completion call requires.

What happens if I forget to call the completion endpoint?
The uploaded parts remain unprocessed. Nothing else in the documented sequence triggers transcoding, the completion call is what tells AIOZ Stream the file is whole.

Does AIOZ Stream support resuming an interrupted upload?
Not in any documented way. There's no endpoint to check which parts the server already has, unlike protocols such as tus that expose an offset-check mechanism for exactly this case.

Should I implement this chunking loop myself if I'm using Node.js?
No, use the SDK's uploadVideo() or the three explicit SDK calls instead. This raw approach is for other languages or for cases needing direct control the SDK doesn't expose.

What is the MD5 hash parameter actually validating?
The integrity of that individual part's bytes as received by the server, not the whole file. Each part gets its own hash, computed before that part is sent.

Related Reading

• Import Existing HLS Video Without Re-Encoding: the alternative, asset-transfer ingestion path for content that's already encoded as HLS elsewhere
• Handling API Rate Limits in Production: the upload-specific 100 req/min limit that applies directly to chunked uploads
• Event-Driven Video Pipelines with AIOZ Stream Webhooks: what to listen for once an upload like this one finishes
• How Video Segmentation and M3U8 Manifests Actually Work: the different, playback-side "chunking" this article's upload chunking is often confused with
• Podcast and Audio Hosting with the AIOZ Stream API: this same chunking sequence applied to audio uploads
• How to Encode 4K/8K Video via the API: H.264 vs H.265: the resolution/codec side of the same large-file upload this article covers
• Getting Started with the AIOZ Stream Node.js SDK: the SDK methods that wrap this entire process into one or three calls
• AIOZ Stream API Keys: the upload-only key scope appropriate for this kind of endpoint
• AIOZ Stream Developer Guide: the full API and SDK surface this upload sequence is part of

References

• AIOZ Stream Media Video API documentation: the create/part/complete endpoints, parameters, and 50-200MB chunk-size range cited above
• tus resumable upload protocol: the Upload-Offset/HEAD mechanism used above as a comparison point for what AIOZ's docs don't specify
• Amazon S3 multipart upload limits: the part-size range and last-part exemption cited above as a comparison point