Sorgenti immagine: URL e Base64
In questa pagina
Aggiornato il 3 novembre 2026. Basato sulla pagina Image Editing e sul riferimento API Immagini di xAI: un’immagine sorgente può essere specificata anche utilizzando l’
file_iddi un file presente nelle API Files, come alternativa esclusiva all’url. Fonti: Image Editing · Images API.
Fornire immagini all’endpoint di modifica
L’endpoint di modifica accetta immagini sorgente in tre forme: un URL pubblico, un Data URI Base64 o l’file_id di un file già caricato nelle API Files di xAI. Ognuna ha i suoi casi d’uso; padroneggiarle ti permette di costruire pipeline di modifica flessibili.
Formato URL
Il formato URL è l’opzione più comoda finché l’immagine è già online: niente da codificare, un payload minuscolo e una richiesta che rimane leggibile nei log. Il vincolo chiave qui è pubblico: l’immagine deve essere recuperabile dai server xAI senza sessione né token.
payload = {
"model": "grok-imagine-image",
"prompt": "Add a gold frame around this image",
"image": {
"url": "https://exemple.com/ma-photo.jpg"
}
}
Vincoli dell’URL
- L’URL deve essere pubblicamente accessibile (niente link protetti da autenticazione)
- I formati supportati sono JPEG, PNG e WebP
- L’immagine deve essere accessibile rapidamente (evita server lenti)
Utilizzare gli URL di output dell’API
È questo che rende pratica la modifica multi-passaggio: l’output di una modifica diventa l’input per la successiva, senza mai scaricare l’immagine sulla tua macchina locale. Una precisazione tuttavia: questi URL scadono, quindi la catena deve eseguirsi in un colpo solo. Per un flusso di lavoro distribuito nel tempo, scaricala tra ogni passaggio.
import requests
import os
headers = {
"Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
"Content-Type": "application/json"
}
# Genera un'immagine
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"]
# Modifica l'immagine generata
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 Data URI Base64
Per le immagini archiviate localmente o generate dinamicamente, usa il formato Data URI Base64:
import base64
# Leggi un'immagine locale
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
}
}
Quando usare il Base64?
Il criterio è semplice: il Base64 è necessario ogni volta che usare un URL pubblico sarebbe una deviazione inutile. Questo vale per le immagini locali non ospitate da nessuna parte: caricarle su un server solo per renderle accessibili all’API aggiunge un passaggio e un ritardo senza valore. Vale anche per le immagini generate in memoria dalla tua applicazione: un grafico prodotto al volo, uno screenshot di un rendering o una miniatura composta dinamicamente non hanno mai bisogno di toccare il disco. Il Base64 risponde anche a un’esigenza di privacy: un’immagine codificata nel corpo della richiesta non è mai esposta su un server pubblico, nemmeno temporaneamente, e semplifica l’architettura: una pipeline automatizzata che concatena generazione, modifica e salvataggio funziona end-to-end senza hosting intermedi da provisionare, mettere in sicurezza e pulire.
Attenzione alle dimensioni
Il Base64 gonfia il payload di circa un terzo, cosa trascurabile per una miniatura ma significativa per una foto di diversi megabyte: tempi di caricamento più lunghi e rischio di superare i limiti di dimensione della richiesta. La regola pratica: se l’immagine è già accessibile online, usa l’URL; se è locale, il Base64 è più semplice che ospitarla solo per l’occasione.
Terza opzione: un file dalle API Files
Un’immagine già caricata nelle API Files di xAI si specifica tramite il suo identificatore, invece che con un URL. I due campi sono mutualmente esclusivi: un oggetto image contiene o url o file_id.
payload = {
"model": "grok-imagine-image",
"prompt": "Add snow to the landscape",
"image": {"file_id": "file_abc123"}
}
Questa è la scelta naturale per un’immagine riutilizzata in più modifiche: viene inviata una sola volta e non deve essere pubblica.
Funzione di utilità
Ecco una funzione che gestisce automaticamente entrambi i formati:
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}")
Questa funzione rileva automaticamente se la sorgente è un URL o un percorso di file locale e formatta l’oggetto di conseguenza.
Esercitazione pratica
Testa entrambi i formati con la stessa immagine e lo stesso prompt per verificare che entrambi i percorsi funzionino; le immagini risultanti varieranno da esecuzione a esecuzione, come per qualsiasi generazione:
# Tramite URL
payload_url = {
"model": "grok-imagine-image",
"prompt": "Add snow to the landscape",
"image": {"url": "https://exemple.com/paysage.jpg"}
}
# Tramite Base64
payload_b64 = {
"model": "grok-imagine-image",
"prompt": "Add snow to the landscape",
"image": prepare_image_source("paysage.jpg")
}
Punti chiave
- Tre forme di input: URL pubblico, Data URI Base64 o
file_iddalle API Files - Gli URL temporanei restituiti dall’API possono servire come sorgenti per la modifica
- Il Base64 aumenta la dimensione del payload di circa il 33%
- Crea una funzione di utilità per gestire automaticamente entrambi i formati
- L’URL deve essere pubblicamente accessibile per funzionare