Multipart Image Upload: A Practical Guide for Web, Mobile and Backend
Part 1: Understanding Chunked Multipart Upload (this post)
Part 2: Chunking the Image Locally
Part 3: Building the Multipart Upload API
Part 4: Making Uploads Reliable and Resumable
Part 5: Production Architecture and Cross-Platform Implementation
No code in this one. Before writing any, we need to agree on what the words mean and what the protocol looks like, because parts 2 to 5 lean on both.
Why one big request breaks
The simplest upload is a single POST with the whole image in the body. On office Wi-Fi it works fine. On a phone it fails in the same few ways, over and over.
Say a 12 MB photo takes 30 seconds on a weak mobile connection. The signal drops at second 25. The connection closes, the server throws away what it got, and the user starts from byte zero.
It gets worse from there:
- Gateways and load balancers often cut requests off after 30 to 60 seconds, however healthy the connection is.
- Proxies cap request body size, and raising the cap for every endpoint is a bad trade.
- A server that buffers the body holds all of it in memory, once per request.
- The client only ever sees "uploading", then "done" or "failed". There's no middle state to recover from.
Chunking fixes this by making each request small enough that failing is cheap, and by making the server remember what already arrived.
What chunking means
You read the file's bytes and cut them into consecutive ranges. A 5.5 MB file with a 1 MB chunk size becomes six ranges: 0 to 1 MB, 1 to 2 MB, and so on, ending with a 0.5 MB piece. Each range goes in its own request. The server stores them, and when all have arrived it joins them in order to rebuild the original file, byte for byte.
One thing people get wrong early: a chunk is not a smaller image. It's a slice of raw bytes. Chunk 3 on its own isn't a valid JPEG, and it only means something next to chunks 2 and 4. Part 2 goes into this.
Chunk, packet, multipart
These three get mixed up all the time.
A packet is a TCP/IP thing. The network stack already splits your data into packets of about 1,500 bytes and reassembles them. You don't see it and can't control it. Chunking happens above that layer.
A chunk is an application-level decision. You split the file into ranges and send each one in a separate HTTP request. You pick the size and the rules.
Multipart is a request encoding, multipart/form-data. One HTTP body carries several named fields, binary files included, separated by a boundary string. It's what browsers use for file inputs.
So "chunked multipart upload" means: cut the file into chunks, and send each as a multipart/form-data request with a few metadata fields next to it. It has nothing to do with Transfer-Encoding: chunked, which is an HTTP mechanism for streaming a body of unknown length.
Don't split into "8 pieces"
The first instinct is usually "I'll divide the image into 8 parts". That fixes the wrong number.
With a fixed part count, chunk size floats with the file. A 200 KB image becomes eight 25 KB requests, which is mostly overhead. A 400 MB video becomes eight 50 MB requests, as fragile as the single upload you were trying to avoid.
Fix the chunk size and let the part count follow:
totalParts = ceil(fileSize / chunkSize) With 1 MB chunks, the 200 KB image is one part and the 400 MB file is 400. Request size stays predictable, so retry cost and timeouts do too. Real chunk sizes range from a few hundred KB on bad mobile networks to 5 to 8 MB on good ones. S3 requires at least 5 MB for every part except the last, so that's a floor if you ever move to it.
The three identifiers
The server has to answer three questions about every chunk it receives.
uploadId answers which upload the chunk belongs to. The server creates it when the upload starts and the client attaches it to every part. Many users upload at the same time, and this is what keeps them apart.
partNumber answers where the chunk goes. The bytes carry no position information, so the number does. Use 1-based numbering on every client and server, and write it down somewhere.
totalParts answers how many chunks to expect. Sending it with each part lets the server check completion without depending on arrival order.
How the server knows first and last
It doesn't guess from arrival order. The first part is the one with partNumber == 1, and the last is partNumber == totalParts. Parts can arrive in any order, so "the last request received" tells you nothing. The upload is complete when the server holds every number from 1 to totalParts, and the client then confirms with an explicit complete call.
Sequential or parallel
Sequential means send part 1, wait for the response, send part 2, and so on. It's simple, easy on the network and easy to debug, but each part waits for a full round trip.
Parallel means several parts in flight at once. It's faster when there's bandwidth to use, but you need a concurrency limit, and parts arrive out of order.
The protocol doesn't care which you pick, since every part identifies itself. I'd start sequential, get everything else working, and add a small parallel pool later. Part 4 covers that.
The architecture
Original Image │ ▼ Local Chunking │ ┌────────────┼────────────┐ ▼ ▼ ▼ Part 1 Part 2 ... Part N │ │ │ └────────────┼────────────┘ ▼ Server │ ▼ Reconstruct File All the cutting happens on the client before any request goes out. The server never holds the whole file at once. It tracks which parts it has and assembles them at the end.
The protocol
Four endpoints are enough:
POST /uploads create an upload, returns uploadId POST /uploads/{uploadId}/parts send one chunk (called once per part) GET /uploads/{uploadId}/status which parts has the server received? POST /uploads/{uploadId}/complete assemble the final file A typical session goes like this:
- The client calls
POST /uploadswith the file name, size and content type. The server replies with anuploadIdand the chunk size it wants. - The client works out
totalPartsand sends each part with itspartNumberandtotalParts. - If something fails, the client calls
/statusto see what the server already has, and sends only what's missing. - Once everything is there, the client calls
/complete. The server checks the parts, assembles the file and returns its location.
The server owns the uploadId and, ideally, the chunk size, so you can change it in one place later. The client owns the slicing.
Next, in part 2, we write the chunking code on web, Flutter, Python and .NET, starting from a 5.5 MB image and a 1 MB chunk size.

