Parámetro detail: auto, low y high
En esta página
Control de la precisión del análisis
Cuando envías una imagen a Grok, puedes controlar el nivel de detalle del análisis mediante el parámetro detail. Este parámetro afecta directamente a la calidad de la respuesta, al tiempo de procesamiento y al consumo de tokens.
Comprender este parámetro es fundamental para optimizar costes y ajustar la precisión a cada caso de uso.
Los tres niveles de detalle
La API de xAI ofrece tres valores para el parámetro detail:
Auto (valor predeterminado)
Si no especificas el parámetro detail, el modelo utiliza auto. Evalúa automáticamente el nivel de detalle necesario en función de la imagen y de tu prompt.
{
"type": "input_image",
"image_url": "https://exemple.com/photo.jpg"
}
Este es el comportamiento recomendado para la mayoría de los casos de uso. El modelo adapta su estrategia de análisis según la complejidad percibida de la imagen y la pregunta formulada.
Low (rápido y económico)
El modo low realiza un análisis rápido de la imagen utilizando menos tokens. Es la opción ideal cuando necesitas una comprensión general sin entrar en detalles finos.
{
"type": "input_image",
"image_url": "https://exemple.com/photo.jpg",
"detail": "low"
}
Casos de uso para low:
- Clasificar el contenido de una imagen (paisaje, retrato, documento, etc.)
- Identificar el sujeto principal de una foto
- Ordenar rápidamente un lote de imágenes
- Comprobar si una imagen cumple un criterio sencillo
High (lento y detallado)
El modo high fuerza un análisis exhaustivo de la imagen. El modelo examina cada zona a la máxima resolución, lo que consume más tokens pero genera descripciones mucho más precisas.
{
"type": "input_image",
"image_url": "https://exemple.com/photo.jpg",
"detail": "high"
}
Casos de uso para high:
- Leer texto fino en una imagen (OCR)
- Analizar gráficos con leyendas detalladas
- Detectar defectos en fotos de productos
- Examinar capturas de pantalla de interfaces complejas
Comparación de los niveles
| Parámetro | Velocidad | Tokens | Precisión |
|---|---|---|---|
| auto | Variable | Variable | Adaptativa |
| low | Rápida | Menos tokens | General |
| high | Lenta | Más tokens | Detallada |
Sintaxis por API
La ubicación del parámetro detail varía según la API que utilices.
Responses API (recomendada)
response = client.responses.create(
model="grok-4.5",
input=[
{
"type": "input_image",
"image_url": "https://exemple.com/photo.jpg",
"detail": "high"
},
{
"type": "input_text",
"text": "Lee todo el texto visible en esta imagen."
}
]
)
Chat Completions API (legada)
response = client.chat.completions.create(
model="grok-4.5",
messages=[{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://exemple.com/photo.jpg",
"detail": "high"
}
},
{
"type": "text",
"text": "Lee todo el texto visible en esta imagen."
}
]
}]
)
Ten en cuenta que en Chat Completions, detail está anidado dentro del objeto image_url, mientras que en la Responses API se encuentra al mismo nivel que image_url.
Estrategia de optimización
En producción, una buena práctica consiste en adaptar el nivel de detalle según el tipo de tarea:
def analizar_imagen(image_url, tarea):
# Tareas sencillas → low para ahorrar costes
if tarea in ["clasificar", "ordenar", "identificar_sujeto"]:
detalle = "low"
# Tareas complejas → high para precisión
elif tarea in ["ocr", "grafico", "defecto_producto"]:
detalle = "high"
# Por defecto → dejar que el modelo decida
else:
detalle = "auto"
return client.responses.create(
model="grok-4.5",
input=[
{"type": "input_image", "image_url": image_url, "detail": detalle},
{"type": "input_text", "text": f"Tarea: {tarea}"}
]
)
Este enfoque te permite reducir significativamente los costes de tokens en tareas sencillas, manteniendo al mismo tiempo la máxima precisión donde sea necesario.
Puntos clave
- El parámetro
detailcontrola la profundidad del análisis de imágenes auto(predeterminado) deja que el modelo decida; es la opción recomendadalowes rápido y económico, adecuado para tareas de clasificaciónhighes lento pero preciso, adecuado para OCR y análisis de grano fino- Adapta el nivel de detalle al tipo de tarea para optimizar costes