How to Encode Files to Base64 for APIs
Many REST APIs accept file data not as a multipart upload but as a Base64-encoded string inside a JSON body. Email APIs, document processing services, image recognition endpoints, and e-signature platforms all use this pattern. If you have never done it before, figuring out the correct encoding and the expected JSON field format can waste an hour. This guide walks through encoding files to Base64 for API use — in the browser with the WikiPlus tool, in JavaScript, in Python, and in cURL — so you can integrate quickly and correctly.
Why APIs Use Base64-Encoded Files
HTTP supports two main approaches for sending files to an API: multipart/form-data and inline Base64 in a JSON body. Multipart form data is the traditional approach. The file is sent as a separate part of the HTTP request with its own headers specifying the content type and filename. This is efficient for large files because the binary data travels as binary bytes with minimal overhead. Inline Base64 encoding embeds the file directly inside a JSON payload as a string field. This approach has become popular for several reasons. First, it keeps the entire request as a single JSON document, which is simpler to construct and log. Second, it works well when the file is small (under a few hundred kilobytes). Third, some API designs prefer a uniform JSON structure where all input — text fields and file data — arrives in one document. Common APIs that use Base64 for files include: SendGrid and Mailgun (email attachments), Google Cloud Vision and AWS Rekognition (image data), DocuSign and HelloSign (PDF documents), Twilio (MMS image data), and many mobile push notification services (icon images). The trade-off is size. A 100 KB image becomes roughly 133 KB after Base64 encoding, and then JSON string escaping may add a small additional overhead. For large files — anything over 1 MB — multipart upload is almost always the better choice. For thumbnails, icons, certificates, and short documents, Base64 in JSON is clean and convenient.
Encoding a File in the Browser with WikiPlus
The WikiPlus Base64 Encoder/Decoder handles file encoding entirely in your browser using the FileReader API. No data leaves your device, which is important when encoding sensitive documents like contracts or personal photographs. To encode a file: open the tool, click the File tab, and drag your file onto the upload area or click to browse. Supported types include any file format — images, PDFs, audio, ZIP archives, and more. The FileReader API reads the file as an ArrayBuffer and the tool encodes it to Base64. The output appears in the text area below. By default, the tool provides the full data URI format: data:image/jpeg;base64,/9j/4AAQ... — this is the format required for HTML src attributes and CSS background-image values. For most API use cases, you only need the raw Base64 string without the data URI prefix. The prefix ends at the comma after base64,. Everything after that comma is the pure encoded data. Copy just that portion for your API payload. For example, if your API expects a payload like {"document": "<base64string>"}, you would paste everything after the comma into that field. If your API documentation specifies a particular content type header like Content-Transfer-Encoding: base64, make sure you are sending the raw Base64 bytes — not the data URI wrapper — as the request body or field value.
Encoding Files in JavaScript, Python, and cURL
When you need to automate file encoding rather than doing it manually, here are the standard approaches in common languages. JavaScript (Node.js): use the fs module and Buffer class. Read the file with fs.readFileSync() and call .toString('base64') on the buffer. For example: const base64 = fs.readFileSync('document.pdf').toString('base64'). In a browser environment, use FileReader.readAsDataURL() and then slice off the prefix at the comma. Python: use the built-in base64 module. Open the file in binary mode, read it, and call base64.b64encode(). The result is a bytes object — call .decode('utf-8') to get a plain string. Example: import base64; data = base64.b64encode(open('image.jpg','rb').read()).decode(). cURL: when testing an API that accepts Base64 in JSON, you can encode a file on the command line with: base64 -w 0 file.pdf (the -w 0 flag prevents line wrapping on Linux). Pipe the result into your JSON string or store it in a variable. In all cases, double-check whether the API wants just the raw Base64 string, or the full data URI format with the MIME type prefix. Reading the API documentation carefully for example payloads usually makes this clear. When in doubt, try raw Base64 first — it is the more common expectation for REST APIs.
Troubleshooting Common File Encoding Errors
Even with the right tools, file encoding for APIs can produce cryptic errors. Here are the most common problems and how to fix them. Error: Invalid base64 string. This usually means your encoded string contains line breaks. MIME Base64 inserts a newline every 76 characters, but most JSON APIs expect a single unbroken string. Strip all newlines and whitespace from your encoded output before inserting it into the JSON payload. Error: Unexpected character in encoded string. You may have included the data URI prefix (data:image/png;base64,) when the API expected only the raw string. Remove everything up to and including the comma. File decodes but produces wrong file type. Make sure you are reading the source file in binary mode, not text mode. Opening a PDF in text mode on Windows may convert line endings from LF to CRLF, corrupting the binary data. Always use rb mode in Python or the binary Buffer approach in Node.js. Payload too large errors. If your file is over 1 MB, Base64 encoding inflates it by 33%, and many API gateways impose payload size limits (often 1–10 MB for JSON). Consider using multipart/form-data for large files, or compress the file with gzip before encoding if the API supports it. Character encoding confusion. If the API is receiving the Base64 string but producing garbage output, confirm whether the API expects standard Base64 (+, /) or Base64url (-, _). JWTs and some OAuth flows use Base64url. Substitute accordingly before sending.
Frequently Asked Questions
- Should I include the data URI prefix when sending Base64 to an API?
- Usually no. Most REST APIs that accept Base64-encoded files expect only the raw encoded string, without the data:image/jpeg;base64, prefix. The prefix is a browser convention for embedding data inline in HTML and CSS. Check your API's documentation for an example request body — if the example shows a plain Base64 string in the field, omit the prefix. If it shows the full data URI format, include it.
- What is the maximum file size I should Base64-encode for an API?
- As a general rule, keep files under 500 KB before encoding. After the 33% Base64 overhead, that becomes roughly 667 KB in the JSON payload, which is well within most API gateway limits. For larger files — PDFs, high-resolution images, videos — use multipart/form-data or a pre-signed URL upload pattern instead. These approaches stream binary data directly and avoid both the size overhead and potential JSON serialization limits.
- Can I decode a Base64-encoded API response to get the original file?
- Yes. Many APIs return generated files (PDFs, images, reports) as Base64-encoded strings in their JSON responses. To recover the file, decode the Base64 string to bytes and write those bytes to a file with the appropriate extension. In Python: open('output.pdf','wb').write(base64.b64decode(response_string)). In the browser, create a Blob from the decoded bytes and trigger a download. The WikiPlus Base64 tool can also decode pasted strings and offer the result as a file download.