Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Modifica di immagini esistenti (inpainting, outpainting)

Lezione 3 di 12 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Modifica di immagini esistenti
  2. Come funziona la maschera
  3. Inpainting: Sostituire un elemento
  4. Outpainting: Estendere l’immagine
  5. Modifica iterativa
  6. Vincoli chiave
  7. Punti chiave

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-mini e chatgpt-image-latest verranno ritirati il 1° dicembre 2026. Gli esempi ora utilizzano gpt-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à xhigh e max. I modelli GPT Image restituiscono sempre le immagini in base64: il parametro response_format utilizzato 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.