Developer Guide
Base64 Encoding for APIs
Put files in JSON with Base64, or skip it for multipart and presigned URLs. Covers Unicode versus binary, size limits, and why Base64 is not encryption.
JSON is a text format. A JPEG is a byte sequence that is not valid UTF-8. If you stuff those bytes into a JSON string, JSON.parse will not save you — the document is already illegal before it leaves the client. Base64 is the usual escape hatch: turn the bytes into ASCII, put that string in a field, and decode on the other side.
It is not the only hatch. Multipart form uploads and presigned object URLs move large files without inflating them 33% and without parking megabytes in a JSON body. Pick Base64 for small blobs that truly belong next to the other fields. Pick something else when the file is the payload.
JSON cannot hold raw bytes
A JSON string is a sequence of Unicode code points written in UTF-8 on the wire, with quotes and escapes. NUL bytes, invalid UTF-8, and unescaped control characters do not belong there. Base64 maps any byte to a 64-character alphabet so the JSON stays valid text.
That mapping is for binary. If the field is already Unicode text, you do not need Base64 — put the string in JSON, or escape it. /tools/base64 is Unicode-safe when you do encode text (नमस्ते → 4KSo4KSu4KS44KWN4KSk4KWH, 👋🌍 → 8J+Ri/CfjI0=). Use it to inspect a field, not to “protect” a password.
Base64 fields versus multipart versus presigned URLs
A Base64 field is one POST with metadata and file together. The server parses JSON, decodes one string, and writes a blob. That is convenient for avatars under a few hundred kilobytes, tiny PDFs, and test fixtures.
multipart/form-data streams the file as a part. Gateways and language frameworks know how to cap part size and write to disk without holding the whole body as a string. Presigned URLs (S3, GCS, R2) let the client PUT the bytes straight to object storage; your API only stores the resulting key. Use those when the file is large, when you do not want it in application logs, or when many workers should not parse the same 20 MB JSON document.
A worked JSON payload
Keep the field name obvious (content_base64, image_data_uri) so callers know it is encoded. If you send a data URI, the MIME type rides in the prefix; if you send raw Base64, send content_type beside it. Pretty-print the body in /tools/json-formatter before you argue about whether the server “dropped bytes” — trailing commas and smart quotes are more common than Base64 bugs.
For an image, /tools/image-to-base64 already produces data:image/TYPE;base64,…. Some APIs want that whole string. Others want only the payload after the comma. Document which one you expect; they are not interchangeable.
Size, limits, and the 33% tax
Base64 grows the file by about 33%. A 3 MB image becomes about 4 MB of JSON, which may exceed a 1 MB or 2 MB body limit on a reverse proxy. Those limits are configuration, not a law of JSON, but they are why “just Base64 the video” fails in production.
Request logging will also capture the blob unless you redact the field. Prefer a URL or an object key in logs. Decode only in the worker that needs the bytes.
Base64 is not encryption
aGVsbG8= is hello in a different alphabet. Anyone who can read the JSON can decode it. Transport security is TLS. Field-level secrecy is a real cipher and a key you do not commit. Encoding and encryption solve different problems; stacking Base64 on a ciphertext is fine, treating Base64 as the ciphertext is not.
Common pitfalls
URL-unsafe alphabets bite when the string later lands in a query parameter. Standard Base64 uses + and / and padding =. URL-safe mode on /tools/base64 turns +/ into -_ and omits padding: <<??>> encodes to PDw_Pz4-. Use that variant only when the receiver expects it.
Other traps: decoding Unicode text with a binary-only API; double-encoding (Base64 of already Base64); and wrapping MIME line breaks inside a JSON string. Validate the JSON in /tools/json-formatter, then decode the field in /tools/base64.
- JSON strings are Unicode text, not byte arrays.
- Presigned URLs beat Base64 for large objects.
- URL-safe Base64 is a different alphabet — do not mix them.
Worked examples
JSON field with a data URI
{
"user_id": "u_42",
"avatar": "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7"
}The GIF is the standard 1×1 transparent pixel. Format this object in /tools/json-formatter if you need to confirm it is valid JSON.
Unicode text versus binary-looking output
Hello World!SGVsbG8gV29ybGQhDecode that string on /tools/base64 to get Hello World! back. This is encoding, not a secret.
Frequently asked questions
When is multipart better than Base64 in JSON?
When the file is large, when the proxy body limit is tight, or when you already have form-upload tooling. Multipart does not pay the 33% tax.
Can I put Base64 in a query string?
Only the URL-safe variant, or after percent-encoding. Standard + / = will break or be rewritten. Prefer a POST body.
Does thedevtools.in host an upload API?
No. /tools/base64, /tools/json-formatter, and /tools/image-to-base64 run in your browser so you can inspect payloads you already have.
Is a Base64 field GDPR-safe because it is encoded?
No. Encoding is reversible. Treat the field as the original file for privacy, logging, and retention.
Summary
Use Base64 when a small blob must live inside JSON. Use multipart or a presigned URL when the file is the point of the request. Confirm the JSON in /tools/json-formatter, encode or decode the field on /tools/base64, and never confuse that alphabet with encryption.