Ir al contenido principal
Español— Elegir un idioma
Menú

Codificar y enviar imágenes en Base64

Lección 5 de 12 Actualizado el 2 de noviembre de 2026 Desarrollador
En esta página
  1. ¿Por qué usar Base64?
  2. Cuándo usar URL frente a Base64
  3. Codificar una imagen a Base64
  4. Formato Data URI
  5. Ejemplo completo
  6. Codificar imágenes desde otras fuentes
  7. Optimizar el tamaño antes de codificar
  8. Límites que debes conocer
  9. Puntos clave

¿Por qué usar Base64?

En la lección anterior aprendiste a enviar imágenes mediante una URL. Sin embargo, la mayoría de las imágenes que se procesan en entornos empresariales no disponen de una URL: una factura que acaba de llegar por correo electrónico, una captura de pantalla generada por una prueba automatizada o una foto tomada por un operario en una línea de producción. Publicar estos archivos en un servidor accesible desde internet solo para analizarlos sería absurdo y, a menudo, está prohibido.

Aquí es donde entra en juego la codificación Base64. Transforma los datos binarios de una imagen en una cadena de texto que puedes incluir directamente en tu solicitud a la API, sin necesidad de una URL externa ni de un alojamiento intermedio.

Cuándo usar URL frente a Base64

CriterioURLBase64
Imágenes ya alojadasIdealInnecesario
Imágenes localesNo adecuadoIdeal
Imágenes generadas dinámicamenteNo adecuadoIdeal
Latencia de redDepende del servidorNula (incrustada)
Tamaño de la solicitudLigeroMás pesado (~33 %)
Seguridad/privacidadURL públicaDatos dentro de la solicitud

La regla es simple: si la imagen es accesible mediante una URL estable, usa la URL. En caso contrario, usa Base64.

Codificar una imagen a Base64

No se requieren dependencias externas; Python proporciona el módulo base64 en su biblioteca estándar:

import base64

def encode_image(file_path):
    """Codifica un archivo de imagen a una cadena Base64."""
    with open(file_path, "rb") as f:
        return base64.standard_b64encode(f.read()).decode("utf-8")

# Codificar una imagen local
image_b64 = encode_image("captures/screenshot.png")
print(f"Longitud de la cadena Base64: {len(image_b64)} caracteres")

El modo "rb" al abrir el archivo no es opcional: leer una imagen en modo de texto provocará un error de decodificación. Espera cadenas largas: la codificación aumenta el tamaño aproximadamente un 33 % respecto al archivo original, por lo que una imagen de 1 MB genera alrededor de 1,33 MB de texto.

Formato Data URI

La cadena en bruto no es suficiente: la API necesita conocer el formato de la imagen. Por tanto, debes presentarla como un data URI, que antepone a los datos su tipo MIME:

data:image/{formato};base64,{datos_base64}

Los cuatro prefijos utilizables corresponden a los formatos admitidos:

  • data:image/jpeg;base64,...
  • data:image/png;base64,...
  • data:image/gif;base64,...
  • data:image/webp;base64,...

Anunciar un PNG como image/jpeg provoca un error de procesamiento; de ahí la función de detección en el siguiente ejemplo.

Ejemplo completo

Esta es la cadena completa, desde la lectura del archivo local hasta la respuesta del modelo:

import base64
import os
from mistralai.client import Mistral

def encode_image(chemin):
    """Codifica una imagen local a Base64."""
    with open(chemin, "rb") as f:
        return base64.standard_b64encode(f.read()).decode("utf-8")

# Determinar el tipo MIME
def obtenir_mime(chemin):
    """Devuelve el tipo MIME según la extensión."""
    extensions = {
        ".jpg": "image/jpeg",
        ".jpeg": "image/jpeg",
        ".png": "image/png",
        ".gif": "image/gif",
        ".webp": "image/webp"
    }
    ext = os.path.splitext(chemin)[1].lower()
    return extensions.get(ext, "image/jpeg")

# Preparar la imagen
chemin_image = "documents/facture-2024.png"
image_b64 = encode_image(chemin_image)
mime_type = obtenir_mime(chemin_image)
data_uri = f"data:{mime_type};base64,{image_b64}"

# Llamar a la API
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

response = client.chat.complete(
    model="mistral-small-latest",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Extrae toda la información de esta factura."},
                {"type": "image_url", "image_url": data_uri}
            ]
        }
    ]
)

print(response.choices[0].message.content)

Idea clave: el campo siempre se llama image_url, incluso cuando contiene un data URI. La estructura del mensaje no cambia en absoluto respecto a la Lección 4; solo difiere el valor.

Codificar imágenes desde otras fuentes

Un archivo en disco es solo un caso entre muchos. Si tu imagen ya existe en memoria, como un objeto Pillow procedente de una captura o de un paso de procesamiento, escribirla en disco para leerla inmediatamente después sería un rodeo innecesario: un búfer en memoria funciona perfectamente:

import base64
from io import BytesIO
from PIL import Image

def pil_to_base64(pil_image):
    """Convierte una imagen Pillow a un data URI Base64."""
    buffer = BytesIO()
    pil_image.save(buffer, format="PNG")
    b64 = base64.standard_b64encode(buffer.getvalue()).decode("utf-8")
    return f"data:image/png;base64,{b64}"

# Ejemplo con una imagen Pillow
img = Image.open("capture.png")
data_uri = pil_to_base64(img)

La misma lógica se aplica a una imagen recuperada mediante HTTP que no quieras almacenar, por ejemplo porque proviene de un enlace de corta duración:

import base64
import requests

def url_to_base64(url):
    """Descarga una imagen y la convierte a un data URI."""
    response = requests.get(url, timeout=10)
    response.raise_for_status()
    content_type = response.headers.get("Content-Type", "image/jpeg")
    b64 = base64.standard_b64encode(response.content).decode("utf-8")
    return f"data:{content_type};base64,{b64}"

data_uri = url_to_base64("https://example.com/photo.jpg")

Optimizar el tamaño antes de codificar

Una foto de smartphone actual pesa entre 4 y 8 MB, lo que se convierte en casi 10 MB una vez codificada. La API redimensionará la imagen de todos modos, como viste en la Lección 2: estarías pagando por la transferencia sin motivo. Por tanto, redimensiona siempre antes de codificar.

from PIL import Image
from io import BytesIO
import base64

def preparer_et_encoder(chemin, taille_max=1024, qualite=85):
    """Redimensiona, comprime y codifica una imagen."""
    img = Image.open(chemin)

    # Redimensionar si es necesario
    if max(img.size) > taille_max:
        img.thumbnail((taille_max, taille_max))

    # Convertir a JPEG para reducir el tamaño
    buffer = BytesIO()
    img.convert("RGB").save(buffer, format="JPEG", quality=qualite)

    b64 = base64.standard_b64encode(buffer.getvalue()).decode("utf-8")
    taille_ko = len(buffer.getvalue()) / 1024
    print(f"Imagen codificada: {taille_ko:.0f} KB")

    return f"data:image/jpeg;base64,{b64}"

data_uri = preparer_et_encoder("photo_haute_resolution.png")

Mostrar el tamaño final no es solo decorativo: manténlo durante tus pruebas, ya que te indicará de inmediato si tu canalización está enviando 80 KB o 8 MB en cada llamada.

Límites que debes conocer

La codificación Base64 conlleva tres restricciones. La imagen codificada se suma al cuerpo de la solicitud HTTP, por lo que más allá de 10 MB arriesgas tiempos de espera agotados (timeouts). La codificación también carga la imagen completa en memoria: para el procesamiento por lotes, gestiona las imágenes una a una en lugar de construir una lista de mil cadenas codificadas. Por último, a diferencia de las URL, las imágenes en Base64 se retransmiten completas en cada solicitud: analizar la misma factura dos veces implica enviarla dos veces.

Puntos clave

  • Base64 es ideal para imágenes locales o generadas dinámicamente
  • El formato data URI combina el tipo MIME y los datos: data:image/png;base64,...
  • Redimensiona y comprime tus imágenes antes de codificarlas para optimizar la latencia
  • Base64 aumenta el tamaño aproximadamente un 33 %: mantén tus imágenes por debajo de 10 MB
  • Usa URL cuando la imagen ya esté alojada; usa Base64 en todos los demás casos