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

input_image frente a image_url: las dos sintaxis

Lección 12 de 12 Actualizado el 30 de julio de 2026 Principiante
En esta página
  1. Dos API, dos sintaxis
  2. API de Respuestas: input_image (recomendada)
  3. API de Chat Completions: image_url (legada)
  4. Tabla comparativa
  5. Errores de sintaxis comunes
  6. Cuándo usar cada API
  7. Puntos clave
  8. Pon a prueba tus conocimientos

Dos API, dos sintaxis

xAI ofrece dos puntos de conexión (endpoints) para interactuar con Grok, y cada uno utiliza una sintaxis distinta para enviar imágenes. Entender estas diferencias es esencial para escribir código correcto y evitar errores frustrantes.

API de Respuestas: input_image (recomendada)

La API de Respuestas es el punto de conexión principal nuevo de xAI. Las nuevas funcionalidades se incorporan aquí en primer lugar. Esta es la API que debes priorizar para cualquier proyecto nuevo.

Sintaxis

{
  "model": "grok-4.5",
  "store": false,
  "input": [
    {
      "type": "input_image",
      "image_url": "https://exemple.com/photo.jpg",
      "detail": "high"
    },
    {
      "type": "input_text",
      "text": "Describe this image."
    }
  ]
}

Características

  • El tipo es input_image (no image_url)
  • La URL o el Data URI van directamente en image_url (sin objeto anidado)
  • detail se sitúa al mismo nivel que image_url
  • El texto utiliza el tipo input_text
  • El array input sustituye al array messages de la API de Chat Completions

SDK de Python

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": "Describe this image."
        }
    ],
    store=False
)

print(response.output_text)

API de Chat Completions: image_url (legada)

La API de Chat Completions es el punto de conexión heredado (legacy), mantenido para garantizar la compatibilidad con los SDK existentes de OpenAI. Si estás migrando código escrito para OpenAI, esta API facilita la transición.

Sintaxis

{
  "model": "grok-4.5",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "image_url",
          "image_url": {
            "url": "https://exemple.com/photo.jpg",
            "detail": "high"
          }
        },
        {
          "type": "text",
          "text": "Describe this image."
        }
      ]
    }
  ]
}

Características

  • El tipo es image_url (no input_image)
  • La URL se encuentra dentro de un objeto anidado image_url.url (doble anidamiento)
  • detail reside dentro del objeto image_url
  • El texto utiliza el tipo text (no input_text)
  • Los mensajes tienen un role (system, user, assistant)

Python con el SDK de OpenAI

from openai import OpenAI

client = OpenAI(
    api_key="your-xai-key",
    base_url="https://api.x.ai/v1"
)

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": "Describe this image."
            }
        ]
    }]
)

print(response.choices[0].message.content)

Tabla comparativa

Aspecto API de Respuestas Chat Completions
Estado Principal (recomendada) Heredada (compatibilidad)
Tipo de imagen input_image image_url
Tipo de texto input_text text
URL de imagen image_url: "..." image_url.url: "..."
Gestión del estado Con estado (previous_response_id) Sin estado (reenviar todo)
Almacenamiento store: true/false No (sin estado)
Herramientas del servidor web_search, x_search, code_interpreter Limitadas

Errores de sintaxis comunes

Error 1: Mezclar formatos

# INCORRECTO — Sintaxis de Chat Completions en la API de Respuestas
input=[
    {"type": "image_url", "image_url": {"url": "..."}}  # ¡No!
]

# CORRECTO — Sintaxis de la API de Respuestas
input=[
    {"type": "input_image", "image_url": "..."}  # ¡Sí!
]

Error 2: Olvidar la estructura anidada en Chat Completions

# INCORRECTO — URL directa en Chat Completions
{"type": "image_url", "image_url": "https://..."}  # ¡No!

# CORRECTO — Objeto anidado
{"type": "image_url", "image_url": {"url": "https://..."}}  # ¡Sí!

Error 3: Usar “text” en lugar de “input_text”

# INCORRECTO — Tipo "text" en la API de Respuestas
input=[
    {"type": "text", "text": "Describe."}  # ¡No!
]

# CORRECTO
input=[
    {"type": "input_text", "text": "Describe."}  # ¡Sí!
]

Cuándo usar cada API

  • Proyecto nuevo: utiliza la API de Respuestas. Ofrece acceso a las últimas funcionalidades y al almacenamiento de conversaciones.
  • Migración desde OpenAI: comienza con Chat Completions para minimizar los cambios de código y migra gradualmente a la API de Respuestas.
  • Imágenes sensibles: API de Respuestas con store: false o API de Chat Completions (sin estado por naturaleza).

Puntos clave

  • La API de Respuestas usa input_image + input_text; la API de Chat Completions usa image_url + text.
  • La estructura de la URL difiere: directa en Respuestas, anidada en Chat Completions.
  • La API de Respuestas es la opción recomendada para todo el desarrollo nuevo.
  • Nunca mezcles sintaxis de ambas API en la misma solicitud.
  • Comprueba siempre el tipo de objeto (input_image frente a image_url) para evitar errores silenciosos.

Pon a prueba tus conocimientos

Visión de la API de xAI: formatos, tokens, sintaxis, ¿está todo en su sitio?

1. ¿Cómo se envía una imagen a la API?

Respuesta: Mediante URL o Base64, en un mensaje de contenido mixto, respetando el formato y las restricciones de tamaño documentados.

2. ¿Qué controla el parámetro detail (auto, low, high)?

Respuesta: La granularidad del análisis y el coste: low ahorra tokens para casos de uso generales, high maximiza la precisión (OCR, detalles finos) y auto deja que la API decida.

3. ¿Cómo se calcula el coste de una imagen?

Respuesta: En tokens de imagen, desde 256 hasta 1792 dependiendo de la resolución y el detalle: ajustar el tamaño de tus imágenes y el nivel de detalle es la primera palanca de optimización.

4. ¿Qué permite la comparación de múltiples imágenes?

Respuesta: Enviar varias imágenes en una única solicitud y razonar sobre ellas (diferencias, evoluciones, coherencia), sin límite en el número de imágenes por solicitud.

5. ¿input_image o image_url: cuál elegir?

Respuesta: input_image es la sintaxis moderna de la API de Respuestas; image_url persiste como legado de Chat Completions. Para código nuevo, la sintaxis moderna es obligatoria.

Buen formato, buen detalle, buena sintaxis: la visión se pilota como el texto, hasta el último token.