Visión: Analizar imágenes con Grok
En esta página
Comprensión de imágenes con Chat Completions
Los modelos Grok (a partir de grok-4.5) incluyen capacidades de visión que te permiten analizar, describir y razonar sobre imágenes. Utilizas esta función mediante el formato de array del campo content, combinando objetos text e image_url.
Los casos de uso son numerosos: extracción de texto de documentos escaneados (OCR), análisis de gráficos, descripción de interfaces de usuario, comparación visual o interpretación de diagramas técnicos.
Enviar una imagen mediante URL
La forma más sencilla es proporcionar la URL pública de la imagen:
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("XAI_API_KEY"),
base_url="https://api.x.ai/v1"
)
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Describe lo que ves en esta imagen."},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/photo-architecture.jpg",
"detail": "high"
}
}
]
}
]
)
print(response.choices[0].message.content)
Los servidores de xAI descargan la imagen en el momento de la solicitud. Esta debe ser accesible públicamente.
Enviar una imagen en Base64
Para imágenes locales o privadas, utiliza la codificación base64:
import base64
def encode_image(image_path: str) -> str:
with open(image_path, "rb") as f:
return base64.b64encode(f.read()).decode("utf-8")
image_data = encode_image("capture-ecran.png")
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "¿Qué texto es visible en esta captura de pantalla?"},
{
"type": "image_url",
"image_url": {
"url": f"data:image/png;base64,{image_data}"
}
}
]
}
]
)
El formato de la URL es data:image/{formato};base64,{datos}, donde {formato} es jpeg, jpg o png.
Niveles de detalle: auto, low y high
El parámetro detail controla la resolución a la que el modelo analiza la imagen:
detail: “low”
{
"type": "image_url",
"image_url": {
"url": "https://example.com/icone.png",
"detail": "low"
}
}
La imagen se reduce a una baja resolución antes del análisis. Este es el modo más rápido y consume menos tokens. Úsalo para imágenes sencillas: iconos, logotipos, diagramas básicos.
detail: “high”
{
"type": "image_url",
"image_url": {
"url": "https://example.com/document-scan.jpg",
"detail": "high"
}
}
La imagen se analiza en alta resolución. El modelo puede leer texto pequeño, identificar detalles finos y analizar áreas específicas. Este es el modo recomendado para documentos, capturas de pantalla y fotografías detalladas.
detail: “auto”
El modelo elige automáticamente el nivel de detalle en función del tamaño y la complejidad de la imagen. Este es el valor predeterminado si omites el parámetro.
Analizar múltiples imágenes
Puedes enviar varias imágenes en un único mensaje para tareas de comparación o análisis cruzado:
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Compara estas dos versiones del diseño. ¿Cuáles son las diferencias?"},
{"type": "image_url", "image_url": {"url": "https://example.com/v1.png", "detail": "high"}},
{"type": "image_url", "image_url": {"url": "https://example.com/v2.png", "detail": "high"}}
]
}
]
)
No existe un límite en el número de imágenes por solicitud, pero cada imagen consume tokens adicionales.
Restricciones técnicas
Ten en cuenta estos límites al utilizar la visión:
- Tamaño máximo: 20 MiB por imagen
- Formatos admitidos: Solo JPG, JPEG y PNG
- Modelos compatibles: grok-4 y superiores (los modelos antiguos no admiten visión)
- Tokens: las imágenes consumen tokens que se suman al coste de texto de la solicitud
Puntos clave
- La visión utiliza el formato de array del campo
contentcon objetosimage_url - Las imágenes pueden enviarse mediante URL pública o codificadas en base64
- Tres niveles de detalle:
auto(predeterminado),low(rápido/económico) yhigh(detallado) - Tamaño máximo de 20 MiB por imagen, solo formatos JPG y PNG
- Pueden enviarse múltiples imágenes en un único mensaje para comparaciones