URL temporales y estrategias de descarga
En esta página
Lección completada el 3 de noviembre de 2026 basada en las páginas Image Generation e Imagine outputs de xAI: el parámetro
storage_optionsmantiene la imagen en la API de Files y puede crear una URL pública permanente; la documentación no especifica la vida útil de las URL efímeras (los «errores 403 o 404» de la versión anterior no aparecen allí); las imágenes se generan en JPEG por defecto. Fuentes: Image Generation · Imagine outputs.
Gestión de imágenes generadas efímeras
Las URL devueltas por la API de generación y edición de imágenes son temporales: la documentación de xAI las describe como de corta duración sin especificar su vida útil, y solicita que descargues o proceses las imágenes sin demora. Esta restricción impacta directamente en cómo diseñas tus aplicaciones.
El problema de las URL temporales
Cuando utilizas response_format="url" (el valor por defecto), la API devuelve una URL efímera. Tras un periodo no especificado, deja de servir la imagen.
# URL efímera: descargar sin demora
response = client.images.generate(
model="grok-imagine-image",
prompt="A mountain landscape"
)
url = response.data[0].url
Consecuencia: no puedes almacenar estas URL en una base de datos y reutilizarlas más tarde. Debes descargar las imágenes sistemáticamente.
Estrategia 1: Descarga inmediata
La estrategia más fiable consiste en descargar cada imagen tan pronto como se genera:
import urllib.request
import os
from datetime import datetime
def generate_and_save(prompt, output_dir="images"):
"""Genera una imagen y la guarda inmediatamente."""
os.makedirs(output_dir, exist_ok=True)
response = client.images.generate(
model="grok-imagine-image",
prompt=prompt
)
timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
filepath = os.path.join(output_dir, f"gen_{timestamp}.jpg") # JPEG por defecto
urllib.request.urlretrieve(response.data[0].url, filepath)
print(f"Imagen guardada: {filepath}")
return filepath
Estrategia 2: Uso de Base64
Al solicitar la respuesta en Base64, recibes los datos binarios de la imagen directamente, sin depender de una URL temporal:
import base64
response = client.images.generate(
model="grok-imagine-image",
prompt="A mountain landscape",
response_format="b64_json"
)
# Los datos están directamente en la respuesta
image_bytes = base64.b64decode(response.data[0].b64_json)
with open("mountain.jpg", "wb") as f: # JPEG por defecto
f.write(image_bytes)
Ventajas de Base64
La ventaja de Base64 se resume en una palabra: autonomía. La imagen llega directamente en la respuesta JSON, sin depender de una URL temporal que podría caducar antes de que tu código la consuma, y sin una petición HTTP adicional para descargarla; una ida y vuelta de red menos significa un punto de fallo menos en tu canalización.
Inconvenientes de Base64
La contrapartida es mecánica: la codificación Base64 infla la respuesta JSON aproximadamente un 33 %, lo cual te cuesta por triplicado: en tiempo de transferencia de la respuesta de la API, en memoria consumida en el cliente para decodificarla y en complejidad si manipulas múltiples imágenes de alta resolución en la misma solicitud. Para una imagen puntual, es despreciable; para un lote de diez imágenes de 2k, la diferencia se vuelve tangible.
Estrategia 3: Almacenamiento automático en la nube
Para aplicaciones de producción, combina la generación con una subida a tu almacenamiento:
import boto3
import urllib.request
import tempfile
def generate_and_upload_s3(prompt, bucket, key):
"""Genera una imagen y la sube directamente a S3."""
response = client.images.generate(
model="grok-imagine-image",
prompt=prompt
)
# Descargar en un archivo temporal
with tempfile.NamedTemporaryFile(suffix=".jpg", delete=False) as tmp:
urllib.request.urlretrieve(response.data[0].url, tmp.name)
# Subir a S3
s3 = boto3.client("s3")
s3.upload_file(tmp.name, bucket, key)
permanent_url = f"https://{bucket}.s3.amazonaws.com/{key}"
return permanent_url
Estrategia 4: Dejar que xAI almacene la imagen
Cada solicitud de Imagine acepta un parámetro storage_options que guarda la imagen producida en la API de Files de tu equipo y puede crear además una URL pública permanente, para compartir o incrustar. Con el SDK de xAI:
import os
import xai_sdk
client_xai = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))
response = client_xai.image.sample(
prompt="A mountain landscape at sunrise",
model="grok-imagine-image-2.0",
storage_options={"filename": "mountain.jpg", "public_url": True},
)
print(response.file_output.file_id) # identificador estable en la API de Files
print(response.public_url) # URL pública permanente
La respuesta mantiene la URL efímera habitual y añade, para cada imagen, un bloque file_output: file_id, filename y, si se solicita, public_url. Solo filename es obligatorio: sin otras opciones, la imagen se almacena de forma privada, sin caducidad ni URL pública. expires_after (de 3.600 segundos a 30 días) programa la eliminación del archivo, y public_url acepta también su propio expires_after, que no puede superar al del archivo. Un equipo puede tener hasta 1.000 URL públicas activas; más allá de ese límite, o en caso de incidente, la imagen sigue almacenada y la respuesta incluye un public_url_error en lugar de la URL. Vía REST, el mismo objeto storage_options va en el cuerpo de la solicitud, incluso para una edición.
Canalización robusta con reintentos
Las URL temporales pueden fallar ocasionalmente durante la descarga. Implementa un mecanismo de reintento:
import time
import urllib.request
import urllib.error
def download_with_retry(url, filepath, max_retries=3):
"""Descarga una imagen con reintentos en caso de error."""
for attempt in range(max_retries):
try:
urllib.request.urlretrieve(url, filepath)
return True
except urllib.error.URLError as e:
if attempt < max_retries - 1:
wait_time = 2 ** attempt # Retroceso exponencial
print(f"Intento {attempt + 1} fallido, reintentando en {wait_time}s...")
time.sleep(wait_time)
else:
print(f"Fallo tras {max_retries} intentos: {e}")
return False
Buenas prácticas
Toda disciplina emana de un único hecho: las URL son temporales. Por tanto, la descarga debe seguir inmediatamente a la generación, en el mismo flujo de código; cada minuto de diferencia es una ventana donde la imagen puede volverse irrecuperable. Por la misma razón, una URL temporal nunca debe almacenarse en una base de datos como referencia permanente: estará muerta en la siguiente consulta, y este es el tipo de error que solo aparece en producción, días después. En aplicaciones críticas donde la fiabilidad es prioritaria, evita el problema con b64_json, que entrega la imagen en la respuesta, o con storage_options, que la mantiene en xAI con un identificador estable.
La descarga en sí merece tratarse como una operación de red normal: un reintento con retroceso para absorber fallos transitorios, nomenclatura de archivos por marca de tiempo o identificador único para evitar colisiones cuando se ejecutan varias generaciones en paralelo. Finalmente, registra los metadatos —prompt, modelo, parámetros— con cada imagen guardada: seis meses después, cuando necesites regenerar un visual «como aquel pero en 2k», este registro será invaluable.
Puntos clave
- Las URL de salida son temporales: descarga inmediatamente
- El formato
b64_jsonevita el problema de la URL efímera - Base64 aumenta el tamaño de la respuesta aproximadamente un 33 %
- Implementa un reintento con retroceso exponencial para robustez
- En producción, sube a almacenamiento permanente (S3, GCS) o deja que xAI almacene la imagen con
storage_options