Modifiche multi-turno e ritocchi mirati
In questa pagina
Aggiornato il 3 novembre 2026. Basandosi sulla pagina Image Editing, sulla Image Prompting Guide e sul riferimento API Immagini di xAI: l’endpoint
/v1/images/editsnon possiede alcun parametromask, né nel riferimento né nella libreriaxai-sdk1.21.0, contrariamente a quanto affermato nella versione precedente. Il ritocco viene mirato tramite il prompt, mentre una zona viene protetta pixel per pixel applicando una maschera localmente, dopo la modifica. Fonti: Image Editing · Image Prompting Guide · Images API.
Catena di modifiche
La modifica delle immagini diventa davvero potente quando si concatenano più interventi. Il principio, descritto da xAI, è semplice: l’output di una modifica diventa l’input della successiva, permettendoti di partire da un’immagine base per poi aggiungere dettagli, aggiustare lo stile o correggere errori, turno dopo turno.
import requests
import os
headers = {
"Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
"Content-Type": "application/json"
}
def edit_image(image_url, prompt):
"""Modifica un'immagine e restituisce l'URL del risultato."""
response = requests.post(
"https://api.x.ai/v1/images/edits",
headers=headers,
json={
"model": "grok-imagine-image",
"prompt": prompt,
"image": {"url": image_url}
}
)
response.raise_for_status()
return response.json()["data"][0]["url"]
# Turno 1: modifica lo sfondo
url_tour1 = edit_image(
"https://exemple.com/portrait.jpg",
"Replace the background with a modern office overlooking the city. "
"Keep the same person, pose, and framing."
)
# Turno 2: regola l'illuminazione
url_tour2 = edit_image(
url_tour1,
"Make the light warm and dim, like late afternoon. "
"Keep the same person, decor, and framing."
)
# Turno 3: aggiungi un elemento
url_tour3 = edit_image(
url_tour2,
"Place an open laptop on the desk, in front of the person. "
"Keep the same person, lighting, and framing."
)
print(f"Final result: {url_tour3}")
Migliori pratiche per le modifiche multi-turno
La guida xAI consiglia di intervenire quando il soggetto e l’impaginazione sono già buoni e serve cambiare solo uno o tre dettagli; se il soggetto stesso è errato, è meglio rigenerare l’immagine. Ogni turno inizia descrivendo la modifica, per poi specificare in una frase cosa non deve muoversi: il soggetto, l’angolazione, l’inquadratura, il posizionamento degli oggetti. Secondo la guida, due formulazioni falliscono: quella che apre con «mantieni tutto», che non cambia quasi nulla, e quella che copia un prompt intero, che ricompone la scena facendo derivare il soggetto, raddoppiare un oggetto o trasformandolo in un elemento vicino.
Ordina i turni dal generale allo specifico: prima sfondo, composizione e atmosfera, poi accessori e correzioni fini, così una modifica maggiore tardiva non annulla i piccoli ritocchi precedenti.
Due precauzioni di sicurezza completano il metodo. Scarica ogni risultato intermedio non appena viene prodotto: gli URL sono temporanei e perdere il turno 3 di una serie di cinque ti costringerebbe a ripartire dal turno 2. Ispeziona inoltre ogni passaggio prima di concatenare: un difetto introdotto al turno 1, come un dito deformato o un’ombra incoerente, si ritroverà in tutti i turni successivi, poiché ognuno parte dall’immagine precedente.
Mirare una zona tramite il prompt
L’API non accetta maschere: è il prompt a fare da mirino. Indica la parte da modificare nel modo più preciso possibile, per nome, posizione o materiale, e specifica cosa deve rimanere identico.
url_chapeau = edit_image(
url_tour3,
"Replace the person's cap with a wide-brimmed straw hat. "
"Keep the same face, hairstyle, decor, and framing."
)
Quando una correzione non attecchisce, la guida raccomanda di cambiare le parole piuttosto che ripetere la stessa richiesta, designando la parte dell’immagine da correggere e ciò che dovrebbe mostrare. Per assemblare più immagini, ad esempio un prodotto in un arredamento o un personaggio trasferito da un’immagine all’altra, la modifica accetta fino a cinque immagini sorgente (lezione 7).
Proteggere una zona pixel per pixel: la maschera locale
Se una parte dell’immagine non deve spostarsi di un pixel, come un logo, un volto o del testo, applica la maschera localmente dopo la modifica: mantieni la zona originale e prendi dalla modifica solo ciò che si trova al di fuori di questa area. Con Pillow, Image.composite(image1, image2, mask) copia image1 dove la maschera è bianca e mantiene image2 dove è nera:
from PIL import Image, ImageDraw
original = Image.open("original.jpg").convert("RGB")
edite = Image.open("edite.jpg").convert("RGB").resize(original.size)
# Maschera: bianco = prendi la modifica, nero = mantieni l'originale
masque = Image.new("L", original.size, 255)
draw = ImageDraw.Draw(masque)
draw.rectangle([40, 40, 360, 160], fill=0) # zona protetta, es. un logo
resultat = Image.composite(edite, original, masque)
resultat.save("resultat.jpg")
Le tre immagini devono avere le stesse dimensioni. Il ridimensionamento presuppone che la modifica abbia mantenuto le proporzioni della sorgente: verificalo o imponilo tramite il parametro aspect_ratio della richiesta. La maschera non impedisce al modello di toccare la zona, ma ti permette di ripristinarla successivamente.
Pipeline di modifica completa
Ecco un esempio di pipeline strutturata che mantiene la cronologia di ogni turno:
class ImageEditor:
def __init__(self, api_key):
self.headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
self.history = []
def edit(self, image_url, prompt):
response = requests.post(
"https://api.x.ai/v1/images/edits",
headers=self.headers,
json={
"model": "grok-imagine-image",
"prompt": prompt,
"image": {"url": image_url}
}
)
response.raise_for_status()
result_url = response.json()["data"][0]["url"]
self.history.append({
"prompt": prompt,
"input": image_url,
"output": result_url
})
return result_url
Punti chiave
- La modifica multi-turno concatena i risultati: ogni output diventa l’input della modifica successiva
- Intervieni quando soggetto e impaginazione sono buoni e servono cambiare solo uno o tre dettagli
- Ogni turno: prima la modifica, poi ciò che deve rimanere identico
- L’API non ha parametri
mask: mira tramite il prompt e proteggi una zona con una maschera locale applicata dopo la modifica - Gli URL di output sono temporanei: scarica i risultati intermedi