Formato de contenido: cadena simple y matriz de objetos
En esta página
Dos formatos para el campo content
El campo content de cada mensaje acepta dos formatos diferentes en la API de Chat Completions de xAI. La elección depende de lo que envíes al modelo: texto plano o contenido multimodal (texto + imágenes).
Formato de cadena: el caso más común
Para mensajes exclusivamente de texto, el campo content es una cadena simple:
{
"role": "user",
"content": "Explica cómo funciona un transformador."
}
Este es el formato que utilizarás en la inmensa mayoría de los casos. Es sencillo, legible y suficiente para todas las interacciones de texto con Grok.
Para el mensaje system, casi siempre se emplea el formato de cadena:
{
"role": "system",
"content": "Eres un experto en arquitectura de software. Responde en inglés con ejemplos de código en Python."
}
Formato de matriz: contenido multimodal
Cuando necesitas enviar imágenes junto con texto, el campo content se convierte en una matriz de objetos tipados. Cada objeto dispone de un campo type que indica su naturaleza.
{
"role": "user",
"content": [
{
"type": "text",
"text": "¿Qué muestra esta imagen?"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/photo.jpg",
"detail": "high"
}
}
]
}
Tipos de objetos disponibles
La matriz de contenido acepta dos tipos de objetos:
text: un bloque de texto con la propiedadtextimage_url: una referencia a una imagen con la propiedadimage_url
Puedes combinar tantos objetos como necesites en un único mensaje. Por ejemplo, para pedir al modelo que compare dos imágenes:
{
"role": "user",
"content": [
{"type": "text", "text": "Compara estos dos diagramas de arquitectura."},
{"type": "image_url", "image_url": {"url": "https://example.com/schema-v1.png"}},
{"type": "image_url", "image_url": {"url": "https://example.com/schema-v2.png"}}
]
}
El parámetro detail para imágenes
Cada objeto image_url acepta un parámetro opcional detail que controla la resolución del análisis:
auto: el modelo elige automáticamente el nivel de detalle (valor por defecto)low: análisis rápido y económico, suficiente para imágenes sencillas (iconos, diagramas básicos)high: análisis detallado, recomendado para imágenes complejas (documentos, fotografías, interfaces)
{
"type": "image_url",
"image_url": {
"url": "https://example.com/document-scan.jpg",
"detail": "high"
}
}
La elección del nivel de detalle repercute directamente en el número de tokens consumidos y, por tanto, en el coste de la solicitud.
¿Cuándo usar cada formato?
La regla es sencilla:
- Solo texto → formato de cadena (más simple y legible)
- Texto + imágenes → formato de matriz (obligatorio para multimodal)
- Solo imágenes → formato de matriz con únicos objetos
image_url
Un formato de matriz con un único objeto text es funcionalmente equivalente al formato de cadena, pero innecesariamente verboso:
// Equivalente pero innecesariamente complejo
{"content": [{"type": "text", "text": "Hola"}]}
// Prefiere esta forma
{"content": "Hola"}
Restricciones técnicas para imágenes
Antes de enviar imágenes a la API de xAI, ten en cuenta estos límites:
- Tamaño máximo: 20 MiB por imagen
- Formatos aceptados: solo JPG, JPEG, PNG (no se admiten GIF, WebP ni SVG)
- Cantidad: sin límite en el número de imágenes por solicitud
- Modelos compatibles: solo grok-4.5 y superiores
Las imágenes pueden proporcionarse mediante una URL pública o codificadas en base64 dentro de la propia URL (formato data:image/jpeg;base64,...).
Puntos clave
- El campo
contentacepta una cadena simple (texto) o una matriz de objetos (multimodal) - El formato de matriz utiliza objetos con un campo
type:"text"o"image_url" - El parámetro
detail(auto,low,high) controla la resolución del análisis para imágenes - Las imágenes están limitadas a 20 MiB en JPG/PNG y requieren grok-4.5 o superior
- Usa el formato de cadena cuando envíes solo texto: es más legible y sencillo