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

Restricciones: formatos, tamaño y límites

Lección 4 de 12 Actualizado el 30 de julio de 2026 Principiante
En esta página
  1. Reglas básicas
  2. Formatos de imagen aceptados
  3. Tamaño máximo: 20 MiB
  4. Número de imágenes por solicitud: ilimitado
  5. Modelos compatibles
  6. Gestión de errores
  7. Puntos clave

Reglas básicas

Antes de integrar la visión de Grok en tus aplicaciones, debes conocer las restricciones técnicas que impone la API de xAI. Ignorar estos límites provoca errores silenciosos o el rechazo de solicitudes, problemas difíciles de depurar en producción.

Formatos de imagen aceptados

La API de xAI acepta dos formatos de archivo de imagen (tres extensiones: .jpg, .jpeg, .png):

  • JPG (o JPEG) — el formato más común para fotografías
  • PNG — adecuado para capturas de pantalla, diagramas e imágenes con texto

Cualquier otro formato será rechazado. Si trabajas con imágenes WebP, GIF, BMP, TIFF, SVG o HEIC, debes convertirlas antes de enviarlas:

from PIL import Image

def convert_to_jpeg(source_path, output_path):
    img = Image.open(source_path)
    # Convertir a RGB (necesario para JPEG)
    if img.mode in ("RGBA", "P"):
        img = img.convert("RGB")
    img.save(output_path, "JPEG", quality=90)

Error frecuente: imágenes RGBA

Los archivos PNG con transparencia (canal alfa) se aceptan tal cual. Sin embargo, si los conviertes a JPEG, debes eliminar primero el canal alfa, ya que JPEG no admite transparencia.

Tamaño máximo: 20 MiB

Cada imagen no debe superar los 20 MiB (20.971.520 bytes). Si se excede este límite, la API rechazará la solicitud.

Este límite se aplica:

  • Al archivo descargado en el caso de una URL
  • A los datos decodificados en el caso de Base64 (no a la cadena codificada en sí, que es aproximadamente un 33 % más larga)

Comprobar el tamaño antes de enviar

import os

def check_size(image_path, max_mib=20):
    size = os.path.getsize(image_path)
    size_mib = size / (1024 * 1024)

    if size_mib > max_mib:
        raise ValueError(
            f"Imagen demasiado grande: {size_mib:.1f} MiB "
            f"(máx. {max_mib} MiB)"
        )
    return size_mib

Comprimir si es necesario

Para imágenes cercanas al límite, puedes reducir la calidad del JPEG:

def compress_image(path, quality=80, max_size_mib=20):
    img = Image.open(path)
    buffer = io.BytesIO()
    img.save(buffer, "JPEG", quality=quality)

    while buffer.tell() > max_size_mib * 1024 * 1024 and quality > 20:
        quality -= 10
        buffer = io.BytesIO()
        img.save(buffer, "JPEG", quality=quality)

    buffer.seek(0)
    return buffer

Número de imágenes por solicitud: ilimitado

A diferencia de otras API de visión que limitan el número de imágenes por solicitud, la API de xAI no impone ningún límite. Puedes enviar tantas imágenes como necesites en una única solicitud.

No obstante, ten en cuenta que:

  • Cada imagen consume entre 256 y 1792 tokens
  • El contexto total del modelo tiene un tamaño máximo
  • Más imágenes implican mayor latencia y coste

Recomendación práctica

Aunque el límite es teóricamente ilimitado, mantén la prudencia:

# Buena práctica: procesar por lotes
def analyze_batch(images, batch_size=10):
    results = []
    for i in range(0, len(images), batch_size):
        batch = images[i:i + batch_size]
        input_data = []
        for img in batch:
            input_data.append({
                "type": "input_image",
                "image_url": img,
                "detail": "low"
            })
        input_data.append({
            "type": "input_text",
            "text": "Describe brevemente cada imagen."
        })

        response = client.responses.create(
            model="grok-4.5",
            input=input_data
        )
        results.append(response)
    return results

Modelos compatibles

La comprensión de imágenes está disponible en grok-4.5 y versiones superiores. Los modelos anteriores no admiten esta funcionalidad.

Comprueba siempre el modelo que utilizas en tu código:

VISION_MODELS = ["grok-4.5", "grok-4.20-0309-reasoning"]

def supports_vision(model):
    return any(model.startswith(m) for m in VISION_MODELS)

Gestión de errores

Anticipa los errores relacionados con las restricciones validando las imágenes antes de enviarlas:

def validate_image(path):
    errors = []

    # Comprobar formato
    extension = path.lower().rsplit(".", 1)[-1]
    if extension not in ("jpg", "jpeg", "png"):
        errors.append(f"Formato no admitido: {extension}")

    # Comprobar tamaño
    size_mib = os.path.getsize(path) / (1024 * 1024)
    if size_mib > 20:
        errors.append(f"Demasiado grande: {size_mib:.1f} MiB (máx. 20)")

    # Comprobar que es una imagen real
    try:
        img = Image.open(path)
        img.verify()
    except Exception:
        errors.append("Archivo dañado o no es una imagen válida")

    return errors

Puntos clave

  • Solo se aceptan los formatos JPG/JPEG y PNG; convierte los demás
  • Tamaño máximo: 20 MiB por imagen; comprime si es necesario
  • El número de imágenes por solicitud es ilimitado, pero cada imagen consume tokens
  • Solo los modelos grok-4.5 y superiores admiten visión
  • Valida siempre las imágenes antes de enviarlas para evitar errores silenciosos