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

Formato de contenido: cadena simple y matriz de objetos

Lección 3 de 12 Actualizado el 30 de julio de 2026 Desarrollador
En esta página
  1. Dos formatos para el campo content
  2. Formato de cadena: el caso más común
  3. Formato de matriz: contenido multimodal
  4. ¿Cuándo usar cada formato?
  5. Restricciones técnicas para imágenes
  6. Puntos clave

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 propiedad text
  • image_url: una referencia a una imagen con la propiedad image_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 content acepta 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