Fuentes de imagen: URL y Base64
En esta página
Actualizado el 3 de noviembre de 2026. Basado en la página Image Editing y la referencia de la API de Imágenes de xAI: una imagen de origen también puede especificarse mediante el
file_idde un archivo en la API de Files, como alternativa exclusiva aurl. Fuentes: Image Editing · Images API.
Suministro de imágenes al endpoint de edición
El endpoint de edición acepta imágenes de origen en tres formatos: una URL pública, un URI de datos Base64 o el file_id de un archivo ya subido a la API de Files de xAI. Cada uno tiene sus casos de uso; dominarlos te permite construir tuberías de edición flexibles.
Formato URL
El formato URL es la opción más cómoda siempre que la imagen ya esté en línea: nada que codificar, una carga útil minúscula y una solicitud que permanece legible en los registros. La restricción clave aquí es pública: la imagen debe ser recuperable por los servidores de xAI sin sesión ni token.
payload = {
"model": "grok-imagine-image",
"prompt": "Add a gold frame around this image",
"image": {
"url": "https://exemple.com/ma-photo.jpg"
}
}
Restricciones de la URL
- La URL debe ser accesible públicamente (sin enlaces protegidos por autenticación)
- Los formatos admitidos son JPEG, PNG y WebP
- La imagen debe ser accesible rápidamente (evita servidores lentos)
Uso de URLs de salida de la API
Esto es lo que hace viable la edición en varias pasadas: la salida de una edición se convierte en la entrada de la siguiente, sin necesidad de descargar nunca la imagen a tu máquina local. Sin embargo, hay un matiz: estas URLs caducan, por lo que la cadena debe ejecutarse de una sola vez. Para un flujo de trabajo distribuido en el tiempo, descárgala entre cada paso.
import requests
import os
headers = {
"Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
"Content-Type": "application/json"
}
# Generate an image
gen_response = requests.post(
"https://api.x.ai/v1/images/generations",
headers=headers,
json={
"model": "grok-imagine-image",
"prompt": "A medieval castle on a hill"
}
).json()
generated_url = gen_response["data"][0]["url"]
# Edit the generated image
edit_response = requests.post(
"https://api.x.ai/v1/images/edits",
headers=headers,
json={
"model": "grok-imagine-image",
"prompt": "Add a dragon flying over the castle",
"image": {"url": generated_url}
}
).json()
Formato URI de datos Base64
Para imágenes almacenadas localmente o generadas dinámicamente, utiliza el formato URI de datos Base64:
import base64
# Read a local image
with open("photo_locale.jpg", "rb") as f:
image_bytes = f.read()
b64_string = base64.b64encode(image_bytes).decode("utf-8")
data_uri = f"data:image/jpeg;base64,{b64_string}"
payload = {
"model": "grok-imagine-image",
"prompt": "Transform this photo into a vector illustration",
"image": {
"url": data_uri
}
}
¿Cuándo usar Base64?
El criterio es simple: Base64 es necesario siempre que usar una URL pública suponga un rodeo innecesario. Esto aplica a imágenes locales que no están alojadas en ningún sitio: subirlas a un servidor solo para hacerlas accesibles a la API añade un paso y un retraso sin valor. También aplica a imágenes generadas en memoria por tu aplicación: un gráfico producido al vuelo, una captura de pantalla de un renderizado o una miniatura compuesta dinámicamente nunca necesitan tocar el disco. Base64 también aborda una preocupación de privacidad: una imagen codificada en el cuerpo de la solicitud nunca queda expuesta en un servidor público, ni siquiera temporalmente, y simplifica la arquitectura: una tubería automatizada que encadena generación, edición y guardado funciona de extremo a extremo sin necesidad de aprovisionar, asegurar y limpiar un alojamiento intermedio.
Vigila el tamaño
Base64 infla la carga útil aproximadamente un tercio, lo cual es despreciable para una miniatura pero se vuelve significativo para una foto de varios megabytes: tiempos de subida más largos y riesgo de superar los límites de tamaño de solicitud. La regla general: si la imagen ya es accesible en línea, usa la URL; si es local, Base64 es más sencillo que alojarla solo para la ocasión.
Tercera opción: un archivo de la API de Files
Una imagen ya subida a la API de Files de xAI se especifica mediante su identificador, en lugar de una URL. Los dos campos son mutuamente excluyentes: un objeto image contiene o bien url o bien file_id.
payload = {
"model": "grok-imagine-image",
"prompt": "Add snow to the landscape",
"image": {"file_id": "file_abc123"}
}
Esta es la elección natural para una imagen reutilizada en múltiples ediciones: se envía una sola vez y no tiene que ser pública.
Función de utilidad
Aquí tienes una función que gestiona ambos formatos automáticamente:
import base64
import os
def prepare_image_source(source):
"""Prepares an image source for the API (URL or local file)."""
if source.startswith("http://") or source.startswith("https://"):
return {"url": source}
if os.path.isfile(source):
ext = source.rsplit(".", 1)[-1].lower()
mime_map = {"jpg": "jpeg", "jpeg": "jpeg", "png": "png", "webp": "webp"}
mime_type = mime_map.get(ext, "jpeg")
with open(source, "rb") as f:
b64 = base64.b64encode(f.read()).decode("utf-8")
return {"url": f"data:image/{mime_type};base64,{b64}"}
raise ValueError(f"Invalid source: {source}")
Esta función detecta automáticamente si la fuente es una URL o una ruta de archivo local y formatea el objeto en consecuencia.
Práctica guiada
Prueba ambos formatos con la misma imagen y prompt para verificar que ambas vías funcionan; las imágenes resultantes variarán de una ejecución a otra, como en cualquier generación:
# Via URL
payload_url = {
"model": "grok-imagine-image",
"prompt": "Add snow to the landscape",
"image": {"url": "https://exemple.com/paysage.jpg"}
}
# Via Base64
payload_b64 = {
"model": "grok-imagine-image",
"prompt": "Add snow to the landscape",
"image": prepare_image_source("paysage.jpg")
}
Puntos clave
- Tres formas de entrada: URL pública, URI de datos Base64 o
file_idde la API de Files - Las URLs temporales devueltas por la API pueden servir como fuentes de edición
- Base64 aumenta el tamaño de la carga útil aproximadamente un 33 %
- Crea una función de utilidad para gestionar ambos formatos automáticamente
- La URL debe ser accesible públicamente para funcionar