Guide
Subir archivos en Base64 dentro de JSON
JSON no tiene forma nativa de transportar datos binarios. Base64 es la solución alternativa, y las soluciones alternativas tienen un coste.
By Buğra SözeriPublished
El modelo de datos de JSON — definido en RFC 8259 — no tiene un tipo binario nativo. Todo valor es una cadena, un número, un booleano, null, un objeto o un array, y las cadenas deben ser texto Unicode válido. Los bytes de un archivo en crudo pueden contener secuencias que no son texto válido en absoluto, así que no hay forma de meterlos directamente en una cadena JSON. Base64 resuelve esto recodificando el binario en un alfabeto restringido de 64 caracteres ASCII imprimibles — seguro para incrustar en una cadena JSON, un documento XML o una URL, a costa de aproximadamente un 33% más de bytes que el archivo original.
Qué aspecto tiene realmente el payload
Un cuerpo JSON típico de subida de archivo envuelve los datos codificados en un campo junto con los metadatos que el servidor necesita para reconstruir el archivo:
{ "filename": "invoice.pdf", "contentType": "application/pdf", "data": "JVBERi0xLjQK..." }
El servidor decodifica el campo data de vuelta a bytes en crudo al recibirlo — el paso inverso exacto de la codificación — y lo escribe en almacenamiento o lo procesa directamente. Este patrón es habitual en payloads de webhooks y clientes de API que solo quieren hablar JSON, ya que evita la negociación adicional de tipo de contenido que exigen las subidas multipart.
El compromiso: tamaño y límites de petición
| Enfoque | Sobrecarga de tamaño | Mejor para |
|---|---|---|
| Base64 en JSON | ~33% más grande | Archivos pequeños, clientes solo-JSON, webhooks |
| multipart/form-data | Ninguna (sobrecarga mínima de delimitadores) | Archivos grandes, endpoints de subida estándar |
Como la mayoría de los gateways de API, balanceadores de carga y frameworks de servidor imponen un tamaño máximo de cuerpo de petición, la sobrecarga del 33% reduce directamente cuán grande puede llegar a ser realmente el archivo subido. Un gateway limitado a 10 MB, en la práctica, limita las subidas Base64 en JSON a unos 7,5 MB de contenido real de archivo — conviene comprobarlo contra los límites documentados de tu proveedor antes de asumir que un archivo «bajo el límite» pasará realmente una vez codificado.
Cuándo saltarse Base64 por completo
Para cualquier cosa más allá de unos pocos megabytes, o cualquier endpoint donde el tamaño de la petición o la velocidad de subida realmente importen, multipart/form-data es la mejor herramienta: envía los bytes en crudo del archivo con solo una pequeña sobrecarga de marcadores delimitadores, sin el impuesto del 33%. Esto es también lo que usan de forma nativa los formularios HTML simples con <input type="file"> a través de la API FormData. Recurre a Base64 en JSON específicamente cuando el cliente solo pueda enviar JSON, el archivo sea pequeño, o el payload necesite permanecer autocontenido como un único objeto JSON — no como opción predeterminada para toda subida.
Frequently asked questions
- ¿Por qué no puedo poner datos binarios directamente en JSON?
- La gramática de JSON solo define cadenas, números, booleanos, null, objetos y arrays — las cadenas deben ser texto Unicode válido. Los bytes binarios en crudo pueden contener secuencias que no son texto válido en absoluto, así que no se pueden incrustar en una cadena JSON sin convertirlos antes a una representación segura para texto, que es exactamente lo que hace Base64.
- ¿Cuál es el coste en tamaño de codificar un archivo en Base64 para una API JSON?
- Alrededor de un 33% más grande que el archivo original, más lo que añada el escapado de cadenas JSON (normalmente insignificante, ya que el alfabeto de Base64 evita caracteres que necesiten escaparse). Un PDF de 3 MB se convierte en aproximadamente 4 MB de texto Base64 dentro del cuerpo JSON.
- ¿Cuándo debería usar multipart form data en lugar de Base64 en JSON?
- Para archivos grandes, o cualquier subida donde el tamaño de la petición importe: multipart/form-data transmite el archivo como bytes en crudo sin sobrecarga de codificación, y es el enfoque estándar para endpoints de subida de archivos (incluidos los formularios HTML simples). Base64 en JSON es más común para archivos pequeños, clientes de API que solo hablan JSON, o payloads de webhooks que necesitan quedar autocontenidos en un único objeto JSON.
- ¿Base64 en JSON cuenta para los límites de tamaño de petición?
- Sí, y la sobrecarga del 33% hace que se llegue al límite antes. Si un gateway de API o un servidor limita los cuerpos de petición a, digamos, 10 MB, un archivo codificado en Base64 debe pesar menos de unos 7,5 MB en crudo para caber — conviene comprobarlo antes de asumir que un archivo «bajo el límite» realmente se subirá una vez codificado.
Sources & references
Authoritative references cited by this piece. Verified by Buğra Sözeri on the dates shown and re-checked at every deploy.
- RFC 8259 — The JavaScript Object Notation (JSON) Data Interchange Format — La especificación de JSON, que solo define valores de texto — sin tipo binario nativo(as of )
- RFC 4648 — The Base16, Base32, and Base64 Data Encodings — La codificación usada para representar binario como una cadena segura para JSON(as of )
- MDN — Using FormData objects — La alternativa multipart que evita la sobrecarga de Base64 en subidas de archivos(as of )
Related
Published September 25, 2026