URL temporanei e strategie di download
In questa pagina
Lezione completata il 3 novembre 2026 basata sulle pagine Image Generation e Imagine outputs di xAI: il parametro
storage_optionsmantiene 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.
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_jsonevita 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