input_image frente a image_url: las dos sintaxis
En esta página
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(noimage_url) - La URL o el Data URI van directamente en
image_url(sin objeto anidado) detailse sitúa al mismo nivel queimage_url- El texto utiliza el tipo
input_text - El array
inputsustituye al arraymessagesde 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(noinput_image) - La URL se encuentra dentro de un objeto anidado
image_url.url(doble anidamiento) detailreside dentro del objetoimage_url- El texto utiliza el tipo
text(noinput_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: falseo API de Chat Completions (sin estado por naturaleza).
Puntos clave
- La API de Respuestas usa
input_image+input_text; la API de Chat Completions usaimage_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_imagefrente aimage_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.