Modifica di immagini esistenti (inpainting, outpainting)
In questa pagina
Aggiornato il 2 novembre 2026 — Modelli immagine.
gpt-image-1, il modello per cui questo corso era stato originariamente scritto, è stato deprecato il 23 ottobre 2026. Inoltre,gpt-image-1.5,gpt-image-1-miniechatgpt-image-latestverranno ritirati il 1° dicembre 2026. Gli esempi ora utilizzanogpt-image-2.5-sunburst, che offre la massima precisione per le modifiche;gpt-image-2.5-flareè più veloce per la generazione generale. Entrambi i modelli supportano anche le impostazioni di qualitàxhighemax. I modelli GPT Image restituiscono sempre le immagini in base64: il parametroresponse_formatutilizzato dai vecchi modelli DALL·E non è più accettato ed è stato rimosso dal codice. Fonte: Generazione di immagini (OpenAI).
Modifica di immagini esistenti
Il metodo client.images.edit() modifica un’immagine esistente utilizzando una maschera per definire l’area da rigenerare. Questo porta a due casi d’uso distinti, che vale la pena nominare con precisione poiché richiedono maschere diverse. L’inpainting riempie o sostituisce un’area interna: potresti cambiare il cielo in un paesaggio, lo schermo di un computer o il colore di un muro. L’outpainting, al contrario, estende l’immagine oltre i suoi bordi originali, ad esempio trasformando un ritratto quadrato in un banner panoramico.
Come funziona la maschera
La maschera è un’immagine PNG con le stesse dimensioni dell’immagine sorgente. Le aree trasparenti (alfa = 0) indicano dove il modello deve generare nuovo contenuto; le aree opache rimangono intatte. Questa convenzione è controintuitiva all’inizio: istintivamente vorresti “dipingere” ciò che vuoi cambiare, ma in realtà devi ritagliare un buco nella maschera. La chiamata API stessa rimane semplice, richiedendo solo i due file e una descrizione di ciò che deve apparire.
import base64
from openai import OpenAI
client = OpenAI()
response = client.images.edit(
model="gpt-image-2.5-sunburst",
image=open("desk_photo.png", "rb"),
mask=open("desk_mask.png", "rb"),
prompt="A computer screen displaying a modern analytics dashboard"
)
with open("edited_desk.png", "wb") as f:
f.write(base64.b64decode(response.data[0].b64_json))
Non hai bisogno di un editor grafico per creare questa maschera. Pillow può generarne una in poche righe: inizia con un livello completamente opaco corrispondente alle dimensioni della sorgente, quindi disegna la forma che vuoi rendere trasparente. Lo script seguente crea una finestra rettangolare al centro dell’immagine.
from PIL import Image, ImageDraw
# Carica l'immagine sorgente per ottenerne le dimensioni
source = Image.open("desk_photo.png")
width, height = source.size
# Crea una maschera completamente opaca (nera)
mask = Image.new("RGBA", (width, height), (0, 0, 0, 255))
draw = ImageDraw.Draw(mask)
# Disegna un'area trasparente (l'area da modificare)
# Rettangolo al centro dell'immagine
x1, y1 = width // 4, height // 4
x2, y2 = 3 * width // 4, 3 * height // 4
draw.rectangle([x1, y1, x2, y2], fill=(0, 0, 0, 0))
mask.save("desk_mask.png")
print(f"Maschera creata: {width}x{height}, area modificabile al centro")
Inpainting: Sostituire un elemento
Una volta ripetuta questa operazione, ha senso incapsulare la creazione della maschera e la chiamata API in un’unica funzione, parametrizzata dalla regione da modificare. Il prompt dovrebbe quindi descrivere solo il contenuto previsto all’interno dell’area mascherata, mai il resto dell’immagine. L’esempio seguente applica questa funzione a una fotografia di paesaggio, modificando solo i primi 400 pixel superiori — il cielo — per conferirgli un’atmosfera tempestosa.
from openai import OpenAI
from PIL import Image, ImageDraw
import base64
client = OpenAI()
def inpaint_region(image_path, region, prompt, output_path):
"""
Sostituisce una regione rettangolare in un'immagine.
region: tupla (x1, y1, x2, y2) in pixel
"""
# Crea la maschera
source = Image.open(image_path)
mask = Image.new("RGBA", source.size, (0, 0, 0, 255))
draw = ImageDraw.Draw(mask)
draw.rectangle(region, fill=(0, 0, 0, 0))
mask.save("temp_mask.png")
# Chiama l'API
response = client.images.edit(
model="gpt-image-2.5-sunburst",
image=open(image_path, "rb"),
mask=open("temp_mask.png", "rb"),
prompt=prompt
)
# Salva il risultato
with open(output_path, "wb") as f:
f.write(base64.b64decode(response.data[0].b64_json))
print(f"Immagine modificata salvata: {output_path}")
# Esempio: Sostituisci il cielo in una foto di paesaggio
inpaint_region(
image_path="landscape.png",
region=(0, 0, 1024, 400), # Parte superiore = il cielo
prompt="Dramatic sky with purple storm clouds at sunset",
output_path="landscape_sky_edited.png"
)
Outpainting: Estendere l’immagine
Ingrandire un’immagine richiede un passaggio extra perché l’API non può generare contenuto “accanto” a un file direttamente. Devi prima creare una tela più grande, incollare l’originale su di essa e fornire una maschera che protegga esattamente l’area occupata da quell’originale. L’intera logica ruota attorno al calcolo delle nuove dimensioni e della posizione di incollaggio in base alla direzione richiesta.
from openai import OpenAI
from PIL import Image
import base64
from io import BytesIO
client = OpenAI()
def outpaint(image_path, direction, extra_pixels, prompt, output_path):
"""
Estende un'immagine in una data direzione.
direction: 'right', 'bottom', 'left', 'top'
extra_pixels: numero di pixel da aggiungere
"""
source = Image.open(image_path).convert("RGBA")
w, h = source.size
# Calcola le nuove dimensioni
if direction == "right":
new_size = (w + extra_pixels, h)
paste_pos = (0, 0)
elif direction == "bottom":
new_size = (w, h + extra_pixels)
paste_pos = (0, 0)
elif direction == "left":
new_size = (w + extra_pixels, h)
paste_pos = (extra_pixels, 0)
elif direction == "top":
new_size = (w, h + extra_pixels)
paste_pos = (0, extra_pixels)
# Crea la tela estesa (trasparente = area da generare)
extended = Image.new("RGBA", new_size, (0, 0, 0, 0))
extended.paste(source, paste_pos)
# La maschera: trasparente ovunque tranne dove è posizionata l'immagine originale
mask = Image.new("RGBA", new_size, (0, 0, 0, 0))
opaque = Image.new("RGBA", (w, h), (0, 0, 0, 255))
mask.paste(opaque, paste_pos)
# Salva temporaneamente
extended.save("temp_extended.png")
mask.save("temp_mask_outpaint.png")
response = client.images.edit(
model="gpt-image-2.5-sunburst",
image=open("temp_extended.png", "rb"),
mask=open("temp_mask_outpaint.png", "rb"),
prompt=prompt
)
with open(output_path, "wb") as f:
f.write(base64.b64decode(response.data[0].b64_json))
print(f"Immagine estesa salvata: {output_path}")
# Estendi un ritratto verso destra
outpaint(
image_path="portrait.png",
direction="right",
extra_pixels=512,
prompt="Natural continuation of the scene, same lighting and background",
output_path="portrait_extended.png"
)
Nota la formulazione del prompt di estensione: «continuazione naturale della scena, stessa illuminazione e sfondo». Nell’outpainting, non stai descrivendo un nuovo soggetto; stai chiedendo al modello di estendere ciò che vede già. Un prompt troppo creativo produrrebbe una giuntura visibile tra l’originale e l’area aggiunta.
Modifica iterativa
Nulla ti impedisce di concatenare più modifiche sulla stessa immagine, utilizzando ogni output come input per il passaggio successivo. Questo è il modo più affidabile per costruire una composizione complessa: gestisci prima lo sfondo, poi il primo piano, con una maschera dedicata per ogni passaggio, piuttosto che sperare che un singolo prompt risolva tutto in una volta.
import base64
from openai import OpenAI
client = OpenAI()
def edit_step(image_path, mask_path, prompt, output_path):
response = client.images.edit(
model="gpt-image-2.5-sunburst",
image=open(image_path, "rb"),
mask=open(mask_path, "rb"),
prompt=prompt
)
with open(output_path, "wb") as f:
f.write(base64.b64decode(response.data[0].b64_json))
return output_path
# Passaggio 1: Modifica lo sfondo
step1 = edit_step(
"scene.png", "mask_background.png",
"Lush tropical forest background",
"scene_step1.png"
)
# Passaggio 2: Aggiungi un elemento in primo piano
step2 = edit_step(
step1, "mask_foreground.png",
"A colorful macaw parrot perched on a branch",
"scene_step2.png"
)
print(f"Risultato finale: {step2}")
Vincoli chiave
Quattro regole tecniche governano il successo della chiamata. Violare una qualsiasi di esse comporta un errore immediato piuttosto che un risultato degradato.
- L’immagine sorgente e la maschera devono avere le stesse dimensioni
- Entrambi i file devono essere in formato PNG
- La dimensione massima per file è di 4 MB
- La maschera utilizza il canale alfa per definire le aree modificabili
Un’osservazione empirica si aggiunge a questi vincoli: i risultati sono più coerenti quando l’area mascherata rappresenta meno del 50% dell’immagine. Oltre tale soglia, il modello ha troppo poco contesto per fondersi correttamente e otterrai spesso risultati migliori dividendo la tua modifica in due modifiche successive.
Metti questo in pratica con una foto della tua scrivania o con qualsiasi immagine royalty-free: scrivi uno script che generi automaticamente una maschera sul quarto superiore dell’immagine, sostituisca quell’area con un cielo stellato e salvi il risultato localmente.
Punti chiave
- L’inpainting sostituisce il contenuto interno, mentre l’outpainting estende i bordi dell’immagine.
- La maschera deve essere un PNG delle stesse dimensioni dell’originale: le aree trasparenti indicano dove generare, quelle opache proteggono l’immagine.
- Per l’outpainting, devi creare manualmente una tela più grande e incollare l’originale prima di chiamare l’API.
- Le modifiche iterative (passaggio dopo passaggio) offrono un controllo superiore rispetto ai tentativi di modificare tutto in una sola volta.
- Mantieni l’area mascherata sotto il 50% dell’immagine totale per garantire coerenza e qualità nel blending.