Base64 API Upload
Generate the Base64 JSON payload you need to upload files via API. Upload a file, set the field name, and get copy-ready JavaScript, cURL, Python, and PHP code.
Drop a file here or click to choose
Any file type — max 25 MB
When Base64 works for APIs: When the API only accepts JSON and the file is small (under 500 KB), Base64 is a good choice. For larger files, multipart/form-data is typically more efficient — no size overhead, supports streaming, and uses less server memory.
When to Use Base64 in an API
- ✓
JSON-only APIs
The API only accepts application/json — no multipart/form-data endpoint. Embedding Base64 is the only option.
- ✓
Small files (< 500 KB)
Icons, thumbnails, short audio clips, small documents. The ~33% size overhead is acceptable and the payload stays manageable.
- ✓
Atomic requests
You need to send a file and metadata together in a single JSON body — for example, an email attachment with recipient details.
- ✓
Webhook callbacks
A third-party webhook delivers file content inline in a JSON notification payload rather than providing a download URL.
When NOT to Use Base64 in an API
- ✗
Large files (> 1 MB)
A 5 MB PDF becomes ~6.7 MB of Base64 text. This increases memory usage, slows JSON parsing, and wastes bandwidth.
- ✗
Streaming uploads
Base64 in JSON cannot be streamed. The server must receive and parse the full JSON body before processing the file.
- ✗
Multiple file uploads
Sending 10 images as Base64 in one JSON payload creates an enormous request body. Use multipart/form-data instead.
- ✗
Performance-sensitive scenarios
Base64 encoding/decoding and JSON parsing add CPU overhead. For file upload APIs, binary transfer has higher throughput.
Base64 JSON vs multipart/form-data
Choose the right upload method for your use case.
| Comparison | Base64 JSON | multipart/form-data |
|---|---|---|
| Size overhead | +33% over binary | Minimal (byte boundary) |
| Content-Type header | application/json | multipart/form-data |
| Small files (< 500 KB) | ✓ Good | ✓ Good |
| Large files (> 1 MB) | ✗ Not recommended | ✓ Recommended |
| File + JSON metadata in one request | ✓ Simple | Requires boundary parsing |
| Upload progress tracking | ✗ Not supported | ✓ Supported |
| Server-side streaming | ✗ Full body required | ✓ Each part can stream |
| CDN / proxy caching | ✗ POST body not cached | ✗ POST body not cached |
Common API Mistakes with Base64
These mistakes cause hard-to-debug bugs in production.
Sending files over 1 MB as Base64
A 2 MB image becomes ~2.7 MB of Base64 text. JSON parsers must load the entire string into memory, causing slow responses and memory spikes under concurrent load.
Using btoa() directly on binary files
btoa() only handles Latin-1 characters. For binary files (PDFs, images, ZIPs), you must read the file as an ArrayBuffer rather than text before converting to Base64. This tool handles that correctly via FileReader.
Forgetting Content-Type: application/json
Without this header, many servers (Express, FastAPI, Rails) won't parse the request body as JSON. The request reaches the handler but body fields will be undefined or empty.
Not validating MIME type on the server
Clients can send any MIME type field value. Always re-validate the actual file content on the server — never trust the mimeType field from the client.
Double-encoding a Base64 string
If you Base64-encode a string that's already Base64-encoded, the result looks valid but the server can't decode it correctly. Always encode from the original binary data, not from an existing Base64 string.
Frequently Asked Questions
Is Base64 a good way to send files via API?
It depends on the file size and API design. For small files (under 500 KB) in JSON-only APIs, Base64 works well. For larger files or high-traffic upload endpoints, multipart/form-data is more efficient — it avoids the 33% size overhead and supports streaming.
What is the maximum file size for Base64 API uploads?
There's no universal limit, but most API gateways and reverse proxies default to 1–10 MB JSON body size limits. A 5 MB file becomes ~6.7 MB of Base64. Check your server, gateway, and CDN limits before using Base64 for large files.
How do I decode a Base64 file on the server?
Node.js: Buffer.from(base64String, "base64"). Python: base64.b64decode(base64_string). PHP: base64_decode($base64_string). All major runtimes have built-in Base64 decoding. Validate the MIME type after decoding rather than trusting the field from the request.
Is sending files as Base64 in JSON secure?
Base64 is encoding, not encryption. Anyone who intercepts the request can decode it. Always use HTTPS to encrypt the transport layer. For sensitive files, consider encrypting the content before Base64-encoding it.
What is the difference between Base64 and a Data URI?
A Data URI includes a MIME prefix — data:application/pdf;base64,JVBERi0… — and can be embedded directly in an HTML src attribute. A plain Base64 string is just the encoded bytes. For API payloads, use plain Base64. Data URIs are for HTML/CSS embedding.
How do I send multiple files as Base64 in one request?
Use a JSON array: {"files": [{"fileName": "a.pdf", "content": "..."}, {"fileName": "b.png", "content": "..."}]}. However, multiple large files as Base64 creates very large payloads. For batch uploads, multipart/form-data or presigned URLs scale better.