Base64 in APIs

Why Do APIs Use Base64 Encoding?

JSON and XML are text-based formats that cannot contain raw binary data. Binary bytes outside the printable ASCII range would break JSON parsing and corrupt XML documents. Base64 converts binary files (images, PDFs, documents) into text strings containing only ASCII characters that JSON and XML can transport safely.

Using Base64 in a JSON API avoids multipart form data and simplifies client implementations. The client sends a single application/json request body containing both metadata fields and file data in one payload. The server parses one JSON object instead of processing multipart boundaries and separate form fields. This approach is common in APIs that accept user avatars, document attachments, and image uploads under 1 MB.

For a detailed explanation of the Base64 encoding algorithm and character set, see What is Base64.

How Do You Send Base64 Images in API Requests?

Include the Base64-encoded file data as a string field in the JSON request body. Alongside the data field, include metadata fields for the filename, content type, and any other information the server needs to process the file. The server decodes the Base64 string back to binary bytes and stores or processes the file.

POST /api/v1/upload HTTP/1.1
Content-Type: application/json

{
  "name": "profile-photo.png",
  "content_type": "image/png",
  "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJ
          AAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5E
          rkJggg=="
}

Some APIs expect the data URI prefix (data:image/png;base64,) included with the Base64 string; others expect raw Base64 without the prefix. Check the API documentation for the expected format. Use the Base64 Image Encoder to convert an image file to a Base64 string. For encoding non-image files, use the Base64 File Encoder.

How Do You Receive Base64 Data from API Responses?

Parse the JSON response and extract the Base64 string field. Decode the Base64 string to binary data, then create a file object or download link. In JavaScript, the atob() function decodes Base64, and the Blob constructor creates a file object from the decoded bytes.

// Parse API response containing Base64 image data
const response = await fetch('/api/v1/document/123');
const json = await response.json();

// Decode Base64 to binary
const binaryString = atob(json.data);
const bytes = new Uint8Array(binaryString.length);
for (let i = 0; i < binaryString.length; i++) {
  bytes[i] = binaryString.charCodeAt(i);
}

// Create downloadable file
const blob = new Blob([bytes], { type: json.content_type });
const url = URL.createObjectURL(blob);

// Trigger download
const link = document.createElement('a');
link.href = url;
link.download = json.name;
link.click();

To decode and preview Base64 image data from an API response, use the Base64 Image Decoder. For non-image files, use the Base64 File Decoder.

What Is the Difference Between Base64 and Multipart Form Data?

Base64 in JSON and multipart form data are two approaches for transmitting files through HTTP APIs. Each has different tradeoffs in size overhead, implementation complexity, and use cases. The table below compares the key factors.

Base64 encoding is simpler for API clients because the entire request is a single JSON object. Multipart form data is more efficient for large files because it avoids the 33% Base64 overhead. Most HTTP libraries and frameworks provide built-in support for both approaches. Choose based on file size and whether a unified JSON body simplifies your API design.

What Are the Size Limits for Base64 in APIs?

Most API gateways and web servers impose request body size limits. Base64 encoding increases payload size by 33%, so a 7.5 MB file produces a 10 MB Base64 string. The table below lists default body size limits for common platforms.

These limits apply to the raw request body, which includes the full Base64 string plus all other JSON fields. A 750 KB image file becomes approximately 1 MB of Base64 text, which already reaches Nginx's default limit. Adjust server limits or use multipart uploads for larger files. Use the Base64 Size Calculator to determine the encoded size before sending.

How Do You Handle Large Files in APIs?

For files over 1 MB, alternatives to Base64 in JSON reduce bandwidth usage and improve upload reliability. Three common approaches handle large file uploads without Base64 overhead.

Presigned URLs (S3): The API returns a presigned upload URL. The client uploads the file directly to object storage (AWS S3, Google Cloud Storage, Azure Blob) using a PUT request with the raw binary file. No Base64 encoding is needed. The server receives a notification or the client sends the object key in a follow-up API call.

Chunked uploads: The client splits the file into chunks (1-5 MB each) and uploads each chunk in a separate request. The server reassembles the chunks. This approach handles network interruptions gracefully because only the failed chunk needs retransmission.

Multipart form data: The client sends the file as a binary MIME part with Content-Type: multipart/form-data. No Base64 encoding overhead. Most HTTP libraries handle multipart construction automatically.

Base64 in JSON is best suited for thumbnails, avatars, and small documents under 1 MB where the 33% overhead is acceptable and the simplified JSON interface is preferred. For verifying that Base64 data is valid before processing, use the Base64 Validator.

Frequently Asked Questions