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

URL temporales y estrategias de descarga

Lección 13 de 14 Actualizado el 3 de noviembre de 2026 Principiante
En esta página
  1. Gestión de imágenes generadas efímeras
  2. El problema de las URL temporales
  3. Estrategia 1: Descarga inmediata
  4. Estrategia 2: Uso de Base64
  5. Estrategia 3: Almacenamiento automático en la nube
  6. Estrategia 4: Dejar que xAI almacene la imagen
  7. Canalización robusta con reintentos
  8. Buenas prácticas
  9. Puntos clave

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_options mantiene 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.

Temp.
URL de salida
b64
Alternativa persistente
+33 %
Sobrecarga de tamaño Base64
30 días
Almacenamiento de xAI, o ilimitado

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_json evita 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