Restricciones: formatos, tamaño y límites
En esta página
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