Formatos de imagen: URL y Base64
En esta página
Actualizado el 3 de noviembre de 2026. Con la API de Responses, los objetos
input_imageeinput_textse incluyen en elcontentde un mensaje{"role": "user", ...}, no directamente eninput. El ejemplo en Python llamaba anteriormente aclient.responses.create()en el clientexai-sdk, método que no existe, y escribía la clave de API en el código: ahora utilizauser(...)eimage(...)del SDK, leyendo la clave desde el entorno. Se ha añadido la advertencia de xAI sobre el almacenamiento del historial. Código verificado conxai-sdk1.21.0. Fuente: Image Understanding.
Envío de imágenes a Grok
Los modelos Grok desde la versión grok-4.5 en adelante incluyen capacidades de visión. Puedes enviar una o más imágenes en tus solicitudes a la API y el modelo las analizará para responder a tus preguntas. Esto se denomina comprensión de imágenes o visión multimodal.
Antes de profundizar en los casos de uso, es fundamental dominar los dos formatos de envío de imágenes que admite la API de xAI.
URL directa
El método más sencillo consiste en proporcionar la URL pública de una imagen. El modelo la descargará y analizará automáticamente.
Con la API de Responses (endpoint principal):
{
"model": "grok-4.5",
"input": [
{
"role": "user",
"content": [
{
"type": "input_image",
"image_url": "https://exemple.com/photo-produit.jpg"
},
{
"type": "input_text",
"text": "Describe esta imagen en detalle."
}
]
}
]
}
xAI recomienda que, al enviar imágenes, no almacenes el historial de solicitudes y respuestas en sus servidores, ya que la solicitud podría fallar: con la API de Responses, pasa "store": false.
Con la API de Chat Completions (legada, compatible con OpenAI):
{
"model": "grok-4.5",
"messages": [
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://exemple.com/photo-produit.jpg"
}
},
{
"type": "text",
"text": "Describe esta imagen en detalle."
}
]
}
]
}
La URL debe apuntar a un archivo de imagen accesible públicamente. Si la imagen está protegida por autenticación o detrás de una CDN privada, utiliza el formato Base64.
Codificado en Base64 (Data URI)
El segundo formato consiste en codificar la imagen directamente en la solicitud como una cadena Base64 precedida por un prefijo MIME. Este es el método ideal cuando trabajas con imágenes locales, capturas de pantalla o archivos generados dinámicamente.
{
"type": "input_image",
"image_url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
}
El prefijo data:image/jpeg;base64, indica al modelo el tipo MIME de la imagen. Ajústalo según el formato:
data:image/jpeg;base64,para archivos JPG/JPEGdata:image/png;base64,para archivos PNG
Codificación de una imagen en Python
import base64
with open("photo.jpg", "rb") as f:
image_data = base64.standard_b64encode(f.read()).decode("utf-8")
image_url = f"data:image/jpeg;base64,{image_data}"
Codificación en JavaScript/Node.js
import { readFileSync } from 'fs';
const imageData = readFileSync('photo.jpg').toString('base64');
const imageUrl = `data:image/jpeg;base64,${imageData}`;
Diferencias clave entre URL y Base64
| Criterio | URL | Base64 |
|---|---|---|
| Tamaño de la solicitud | Ligero (solo la URL) | Pesado (+33 % respecto al archivo original) |
| Accesibilidad | Requiere imagen pública | Funciona con cualquier archivo local |
| Latencia | Descarga por el servidor | Datos directamente en la solicitud |
| Caso de uso típico | Imágenes web, CDN, almacenamiento en la nube | Archivos locales, capturas de pantalla, subidas |
Combinación de texto e imágenes
El content de un mensaje acepta un array mixto de objetos input_image e input_text, en cualquier orden: puedes alternar libremente texto e imágenes. Con el SDK nativo de xAI, el mismo mensaje se construye con user(), que acepta texto e imágenes creadas por image() en secuencia:
from xai_sdk import Client
from xai_sdk.chat import image, user
client = Client() # clave leída desde XAI_API_KEY
chat = client.chat.create(model="grok-4.5")
chat.append(
user(
"Compara estas dos fotos:",
image(image_url="https://exemple.com/photo1.jpg", detail="high"),
image(image_url="https://exemple.com/photo2.jpg", detail="high"),
"¿Cuáles son las principales diferencias?",
)
)
response = chat.sample()
print(response.content)
image() acepta una URL pública o un Data URI en Base64.
Puntos clave
- Se admiten dos formatos de imagen: URL directa y Base64 (Data URI)
- Los formatos aceptados son únicamente JPG, JPEG y PNG
- Cada imagen no debe superar los 20 MiB
- El número de imágenes por solicitud es ilimitado
- La API de Responses coloca
input_imageen elcontentde un mensaje; Chat Completions usa partesimage_url; el SDK de xAI usaimage()dentro deuser() - Prefiere URL para imágenes públicas y Base64 para archivos locales