Vai al contenuto principale
Italiano— Scegli una lingua
Menu

URL temporanei e strategie di download

Lezione 13 di 14 Aggiornata il 3 novembre 2026 Principiante
In questa pagina
  1. Gestione delle immagini generate effimere
  2. Il problema degli URL temporanei
  3. Strategia 1: Download immediato
  4. Strategia 2: Utilizzo di Base64
  5. Strategia 3: Archiviazione cloud automatica
  6. Strategia 4: Lasciare che xAI archivi l’immagine
  7. Pipeline robusta con retry
  8. Best Practices
  9. Punti chiave

Lezione completata il 3 novembre 2026 basata sulle pagine Image Generation e Imagine outputs di xAI: il parametro storage_options mantiene l’immagine nelle Files API e può generare un URL pubblico permanente; la documentazione non specifica la durata di vita degli URL effimeri (gli “errori 403 o 404” della versione precedente non compaiono qui); le immagini sono restituite in JPEG di default. Fonti: Image Generation · Imagine outputs.

Gestione delle immagini generate effimere

Gli URL restituiti dalle API di generazione ed editing di immagini sono temporanei: la documentazione di xAI li definisce a breve durata senza specificarne la lifespan, e ti chiede di scaricare o elaborare le immagini senza indugio. Questo vincolo impatta direttamente il modo in cui progetti le tue applicazioni.

Temp.
URL di output
b64
Alternativa persistente
+33%
Sovraccarico dimensione Base64
30 giorni
Archiviazione xAI, o illimitato

Il problema degli URL temporanei

Quando usi response_format="url" (il default), l’API restituisce un URL effimero. Dopo un periodo non specificato, smette di servire l’immagine.

# URL effimero: scarica senza indugio
response = client.images.generate(
    model="grok-imagine-image",
    prompt="Un paesaggio montano"
)

url = response.data[0].url

Conseguenza: non puoi memorizzare questi URL in un database e riutilizzarli in seguito. Devi scaricare sistematicamente le immagini.

Strategia 1: Download immediato

La strategia più affidabile consiste nel scaricare ogni immagine non appena viene generata:

import urllib.request
import os
from datetime import datetime

def generate_and_save(prompt, output_dir="images"):
    """Genera un'immagine e la salva immediatamente."""
    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 di default

    urllib.request.urlretrieve(response.data[0].url, filepath)
    print(f"Immagine salvata: {filepath}")
    return filepath

Strategia 2: Utilizzo di Base64

Richiedendo la risposta in Base64, ricevi direttamente i dati binari dell’immagine, senza dipendere da un URL temporaneo:

import base64

response = client.images.generate(
    model="grok-imagine-image",
    prompt="Un paesaggio montano",
    response_format="b64_json"
)

# I dati sono direttamente nella risposta
image_bytes = base64.b64decode(response.data[0].b64_json)

with open("mountain.jpg", "wb") as f:  # JPEG di default
    f.write(image_bytes)

Vantaggi di Base64

Il vantaggio di Base64 si riassume in una parola: autonomia. L’immagine arriva direttamente nella risposta JSON, senza dipendere da un URL temporaneo che potrebbe scadere prima che il tuo codice lo consumi, e senza una richiesta HTTP aggiuntiva per scaricarla: un round-trip di rete in meno significa un punto di guasto in meno nella tua pipeline.

Svantaggi di Base64

Il compromesso è meccanico: la codifica Base64 gonfia la risposta JSON di circa il 33%, cosa che ti costa su tre fronti: tempo di trasferimento della risposta API, memoria consumata sul client per decodificarla e complessità se manipoli più immagini ad alta risoluzione nella stessa richiesta. Per un’immagine singola è trascurabile; per un batch di dieci immagini 2k, la differenza diventa tangibile.

Strategia 3: Archiviazione cloud automatica

Per le applicazioni in produzione, combina la generazione con un upload sul tuo storage:

import boto3
import urllib.request
import tempfile

def generate_and_upload_s3(prompt, bucket, key):
    """Genera un'immagine e la carica direttamente su S3."""
    response = client.images.generate(
        model="grok-imagine-image",
        prompt=prompt
    )

    # Download in un file temporaneo
    with tempfile.NamedTemporaryFile(suffix=".jpg", delete=False) as tmp:
        urllib.request.urlretrieve(response.data[0].url, tmp.name)

        # Upload su S3
        s3 = boto3.client("s3")
        s3.upload_file(tmp.name, bucket, key)

    permanent_url = f"https://{bucket}.s3.amazonaws.com/{key}"
    return permanent_url

Strategia 4: Lasciare che xAI archivi l’immagine

Ogni richiesta Imagine accetta un parametro storage_options che salva l’immagine prodotta nelle Files API del tuo team e può creare inoltre un URL pubblico permanente, da condividere o incorporare. Con l’SDK xAI:

import os
import xai_sdk

client_xai = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

response = client_xai.image.sample(
    prompt="Un paesaggio montano all'alba",
    model="grok-imagine-image-2.0",
    storage_options={"filename": "mountain.jpg", "public_url": True},
)

print(response.file_output.file_id)  # identificatore stabile nelle Files API
print(response.public_url)           # URL pubblico permanente

La risposta mantiene il solito URL effimero e aggiunge, per ogni immagine, un blocco file_output: file_id, filename e, se richiesto, public_url. Solo filename è obbligatorio: senza altre opzioni, l’immagine è archiviata privatamente, senza scadenza né URL pubblico. expires_after (da 3.600 secondi a 30 giorni) programma l’eliminazione del file, e public_url accetta anch’esso il proprio expires_after, che non può superare quello del file. Un team può avere fino a 1.000 URL pubblici attivi; oltre tale limite, o in caso di incidente, l’immagine resta comunque archiviata e la risposta riporta un public_url_error al posto dell’URL. Tramite REST, lo stesso oggetto storage_options va nel body della richiesta, anche per un editing.

Pipeline robusta con retry

Gli URL temporanei possono talvolta fallire durante il download. Implementa un meccanismo di retry:

import time
import urllib.request
import urllib.error

def download_with_retry(url, filepath, max_retries=3):
    """Scarica un'immagine con retry in caso di errore."""
    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  # Backoff esponenziale
                print(f"Tentativo {attempt + 1} fallito, riprovo tra {wait_time}s...")
                time.sleep(wait_time)
            else:
                print(f"Fallito dopo {max_retries} tentativi: {e}")
                return False

Best Practices

Tutta la disciplina nasce da un unico fatto: gli URL sono temporanei. Il download deve quindi seguire immediatamente la generazione, nello stesso flusso di codice: ogni minuto di divario è una finestra in cui l’immagine può diventare irrecuperabile. Per lo stesso motivo, un URL temporaneo non deve mai essere memorizzato in un database come riferimento permanente: sarà morto alla prossima consultazione, e questo è il tipo di bug che appare solo in produzione, giorni dopo. Nelle applicazioni critiche dove l’affidabilità viene prima di tutto, aggira il problema con b64_json, che consegna l’immagine nella risposta, o con storage_options, che la mantiene su xAI con un identificatore stabile.

Il download stesso merita di essere trattato come una normale operazione di rete: un retry con backoff per assorbire i guasti transitori, naming dei file per timestamp o identificatore univoco per evitare collisioni quando più generazioni girano in parallelo. Infine, registra i metadati—prompt, modello, parametri—con ogni immagine salvata: tra sei mesi, quando dovrai rigenerare un visual “come quello ma in 2k”, questo log sarà prezioso.

Punti chiave

  • Gli URL di output sono temporanei: scarica immediatamente
  • Il formato b64_json evita il problema degli URL effimeri
  • Base64 aumenta la dimensione della risposta di ~33%
  • Implementa un retry con backoff esponenziale per robustezza
  • In produzione, carica su storage permanente (S3, GCS), o fai archiviare l’immagine a xAI con storage_options