Cómo convertir imágenes a Base64 para solicitudes de APIs de visión

Por qué las APIs de visión necesitan Base64

Las APIs de visión modernas como GPT-4o de OpenAI, Google Cloud Vision, Anthropic Claude y Qwen-VL aceptan imágenes de dos formas: una URL pública que apunte a la imagen, o los datos de imagen codificados como una cadena Base64 embebida directamente en el cuerpo JSON de la solicitud.

El método de URL es sencillo si tu imagen ya está alojada en línea. Pero en muchos escenarios reales, la imagen está en tu máquina local: una captura de pantalla que acabas de tomar, un escaneo de un documento, un fotograma extraído de un video o una imagen de prueba de tu pipeline de desarrollo. Para estos casos, la codificación Base64 es el camino a seguir. Te permite embeber la imagen directamente en la solicitud de API sin necesidad de subirla a un servidor primero.

Una solicitud típica de API de visión con Base64 se ve así:

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What's in this image?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,iVBORw0KGgo..."
          }
        }
      ]
    }
  ]
}

El desafío está en pasar de tu archivo local a esa cadena Base64, especialmente si necesitas hacerlo repetidamente durante el desarrollo y las pruebas.

Métodos comunes (y sus inconvenientes)

1. Script de Python

import base64

with open("screenshot.png", "rb") as f:
    encoded = base64.b64encode(f.read()).decode()
print(encoded)

Funciona bien, pero necesitas tener Python instalado, escribir (o encontrar) el script y luego copiar la salida desde la terminal. Si estás probando diferentes imágenes repetidamente, ejecutas el script cada vez y luego pegas la salida en tu JSON manualmente.

2. Línea de comandos

# macOS / Linux
base64 -i screenshot.png | pbcopy

# Windows PowerShell
[Convert]::ToBase64String([IO.File]::ReadAllBytes("screenshot.png")) | Set-Clipboard

Rápido si recuerdas la sintaxis, pero la salida es solo una cadena cruda. No puedes verificar lo que tienes: ¿es la imagen correcta? ¿La codificación fue correcta? No lo sabrás hasta que envíes la solicitud de API y revises el resultado.

3. Conversores Base64 en línea

Hay muchos sitios web que ofrecen conversión de archivo a Base64 con arrastrar y soltar. El problema evidente: estás subiendo tu archivo al servidor de alguien más. Para una captura de pantalla de prueba puede estar bien. Para datos propietarios, documentos internos, imágenes médicas o cualquier cosa cubierta por un NDA, no es una opción.

Una forma mejor: pega, previsualiza, copia

ViewJSON ofrece un flujo de trabajo más simple. Pega una imagen directamente en el editor, obtén la cadena Base64 al instante y todo se queda en tu navegador:

1. Abre ViewJSON — Ve a viewjson.net
2. Pega tu imagen — Copia una imagen de cualquier lugar (explorador de archivos, herramienta de capturas, navegador, app de diseño) y pégala directamente en el editor JSON con Ctrl+V
3. Ve la vista previa — ViewJSON convierte automáticamente la imagen a Base64 y la inserta como un valor de cadena JSON. Una vista previa integrada aparece inmediatamente para que puedas verificar que es la imagen correcta.
4. Copia el Base64 — Haz clic en el botón de copiar o selecciona el valor de cadena. Obtienes la cadena Base64 completa, lista para pegar en tu payload de solicitud de API.

El flujo de trabajo completo en acción:

Manejo de cadenas Base64 largas

Las imágenes codificadas en Base64 pueden ser extremadamente largas. Un solo JPEG de alta resolución puede producir más de 100 000 caracteres. Para mantener el editor ágil, ViewJSON trunca automáticamente la visualización de cadenas largas. Pero el truncado es solo visual.

Cuando copias un valor Base64 truncado, el mecanismo de restauración sin pérdida del portapapeles de ViewJSON entra en acción. Detecta que estás copiando una cadena truncada y restaura automáticamente el contenido original completo en tu portapapeles. Siempre obtienes la cadena Base64 completa y sin modificar, nunca una versión truncada que produciría un archivo corrupto.

Construir el payload completo de la API

Una vez que tienes tu cadena Base64, necesitas envolverla en el formato correcto de la API. Aquí tienes ejemplos para las APIs de visión más comunes:

OpenAI GPT-4o Vision

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Describe this image" },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,<TU_BASE64_AQUÍ>"
          }
        }
      ]
    }
  ],
  "max_tokens": 300
}

Google Cloud Vision

{
  "requests": [
    {
      "image": {
        "content": "<TU_BASE64_AQUÍ>"
      },
      "features": [
        { "type": "TEXT_DETECTION" }
      ]
    }
  ]
}

Después de pegar la imagen en ViewJSON, copia la cadena Base64 generada e insértala en tu payload de solicitud de API. También puedes usar el Constructor de Solicitudes API de ViewJSON para configurar URL, método, encabezados y cuerpo, y luego exportar toda la solicitud como un comando cURL.

Privacidad: sin necesidad de subir archivos

A diferencia de los sitios web de conversión Base64 en línea, ViewJSON funciona completamente en tu navegador. La conversión de imagen a Base64 ocurre localmente usando la API FileReader integrada del navegador. Tu imagen nunca se envía a ningún servidor.

Esto lo hace adecuado para convertir imágenes sensibles: escaneos médicos para APIs de IA en salud, documentos internos para servicios de OCR, imágenes propietarias de productos para sistemas de búsqueda visual o cualquier archivo que no querrías subir a un conversor de terceros.

Comparación de métodos