Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Sorgenti immagine: URL e Base64

Lezione 6 di 14 Aggiornata il 3 novembre 2026 Principiante
In questa pagina
  1. Fornire immagini all’endpoint di modifica
  2. Formato URL
  3. Formato Data URI Base64
  4. Terza opzione: un file dalle API Files
  5. Funzione di utilità
  6. Esercitazione pratica
  7. Punti chiave

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_id di 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_id dalle 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