GPT Image 2.5 API: generare e modificare immagini in Python

Invia una POST a https://api.omniakey.com/v1/media/tasks con model impostato su gpt-image-2.5-flare, controlla l'id dell'attività che torna e scarica assets[0].url quando lo stato è succeeded. Il 29 ottobre 2026 abbiamo generato a 1K, 2K e 1536x1024 e modificato la foto di un caffè, poi abbiamo aperto ogni file e letto la dimensione reale in pixel: 1024×1024, 2048×2048, 1536×1024 e 1024×682. La generazione a 1K ha richiesto 29,5 s e quella a 2K 45,2 s.

Quale id del modello 2.5 usare

Usa gpt-image-2.5-flare. È l'id che abbiamo chiamato in ogni esecuzione qui sotto. La pagina del modello GPT-Image 2.5 Flare (verificata il 29 ottobre 2026) indica OpenAI come fornitore, elenca testo in immagine e modifica di immagini e riporta la nota "Guide updated 2026-10-27". La stessa pagina mostra un secondo id 2.5, gpt-image-2.5-sunburst.

Flare copre entrambi i lavori. La generazione invia un prompt; la modifica invia un prompt più un'immagine di partenza. La qualità accetta low, medium o high, e la stessa pagina dice che il livello non cambia il prezzo. Ogni esecuzione qui ha usato medium. Non abbiamo provato sunburst, la qualità low o high, 4K o 3840x2160, maschere o più immagini di riferimento, quindi pianifica con Flare su medium e una sola immagine di partenza finché non provi il resto.

Il codice della richiesta

Lo script qui sotto è quello che abbiamo eseguito, senza modifiche: due funzioni di supporto, poi una chiamata di generazione e una di modifica. Usa solo la libreria standard di Python, legge la chiave da OMNIAKEY_API_KEY e scrive ogni PNG nella cartella da cui lo lanci.

import base64
import json
import os
import time
import urllib.request
import uuid

API = "https://api.omniakey.com/v1/media/tasks"
KEY = os.environ["OMNIAKEY_API_KEY"]
MODEL = "gpt-image-2.5-flare"

def request(method, url, body=None, extra_headers=None):
    headers = {"Authorization": f"Bearer {KEY}", "User-Agent": "omniakey-example/1"}
    data = None
    if body is not None:
        headers["Content-Type"] = "application/json"
        data = json.dumps(body).encode()
    headers.update(extra_headers or {})
    req = urllib.request.Request(url, data=data, headers=headers, method=method)
    with urllib.request.urlopen(req, timeout=120) as resp:
        return json.load(resp)

def run_task(body, out_path):
    task = request("POST", API, body, {"Idempotency-Key": str(uuid.uuid4())})["id"]
    for _ in range(150):
        time.sleep(4)
        state = request("GET", f"{API}/{task}")
        if state["status"] not in ("queued", "processing"):
            break
    if state["status"] != "succeeded":
        raise RuntimeError(state.get("error") or state["status"])
    asset_url = state["assets"][0]["url"]  # signed link: valid for about an hour, so download now
    req = urllib.request.Request(asset_url, headers={"User-Agent": "omniakey-example/1"})
    with urllib.request.urlopen(req, timeout=120) as resp, open(out_path, "wb") as f:
        f.write(resp.read())
    return task

def generate_image(prompt, out_path, size="1K", quality="medium"):
    body = {
        "model": MODEL,
        "type": "image",
        "operation": "generate",
        "input": {"prompt": prompt},
        "parameters": {"size": size, "quality": quality},
    }
    return run_task(body, out_path)

def edit_image(source_path, prompt, out_path, size="1K", quality="medium"):
    with open(source_path, "rb") as f:
        image = base64.b64encode(f.read()).decode()
    body = {
        "model": MODEL,
        "type": "image",
        "operation": "edit",
        "input": {"prompt": prompt, "image": {"data": image, "mime_type": "image/jpeg"}},
        "parameters": {"size": size, "quality": quality},
    }
    return run_task(body, out_path)

if __name__ == "__main__":
    task = generate_image(
        "A small glass greenhouse on a hillside at sunrise, morning fog in the valley, "
        "soft watercolor style, a wooden bench outside the door, no people, no text.",
        "greenhouse.png",
    )
    print("generate task", task)
    task = edit_image(
        "cafe-base.jpg",
        "Change the red bicycle to matte black. Keep everything else exactly the same: "
        "the table, the cup, the window frame and the daylight. Photorealistic, no text, no logos.",
        "cafe-edited.png",
    )
    print("edit task", task)

Authorization: Bearer <key> va in ogni chiamata, e la chiamata di creazione richiede anche un Idempotency-Key, che lo script riempie con un UUID nuovo. Il body imposta type su "image", operation su "generate" o "edit", le parole in input.prompt, e dimensione e qualità in parameters. L'API accetta anche n, e solo 1 è valido, quindi lo script lo omette. Una creazione restituisce HTTP 202 con un id attività, lo stato parte da queued, e il ciclo aspetta 4 s tra i controlli finché lo stato non esce dai due stati di lavoro.

Una modifica aggiunge il JPEG in input.image come oggetto Base64 inline con il suo tipo mime. I body delle richieste, Base64 incluso, sono limitati a 1 MiB, quindi lo script invia un JPEG da 1024 pixel di circa 230 KB.

Le dimensioni provate e i risultati

Quattro esecuzioni, tutte con qualità medium, il 29 ottobre 2026. Tre sono tornate alla dimensione richiesta. La modifica a 1K no, in una delle sue due esecuzioni.

• 1K, generazione — Dimensione in pixel letta dal file: 1024×1024; Data: 29 ottobre 2026
• 2K, generazione — Dimensione in pixel letta dal file: 2048×2048; Data: 29 ottobre 2026
• 1536x1024, generazione — Dimensione in pixel letta dal file: 1536×1024; Data: 29 ottobre 2026
• 1K, modifica — Dimensione in pixel letta dal file: 1024×682; Data: 29 ottobre 2026

La serra qui sotto è una generazione a 1K con lo stesso body della richiesta nel codice sopra.

Due cose da portare via dalla lista. Primo, leggi la dimensione dal file che hai scaricato. La modifica a 1K chiedeva un quadrato ma è tornata a 1024×682, la forma del JPEG 1024×683 che abbiamo inviato, e un'altra esecuzione della stessa modifica a 1K è tornata a 1024×1024. Secondo, la lista di dimensioni nella documentazione dell'API immagini (verificata il 29 ottobre 2026) offre auto, 1K, 2K, 4K e 3840x2160 per questo modello e dice che rifiuta le dimensioni fuori lista prima di qualsiasi addebito; la nostra chiamata a 1536x1024 del 29 ottobre 2026 non è stata rifiutata e ha restituito 1536×1024. Controlla il file reale prima di costruire un layout su una dimensione.

Una modifica conserva la scena e cambia una cosa

Una modifica risponde a due domande: cosa cambia e cosa resta. Abbiamo chiesto un solo cambiamento e indicato le cose che dovevano sopravvivere.

Prompt: "Change the red bicycle to matte black. Keep everything else exactly the same: the table, the cup, the window frame and the daylight. Photorealistic, no text, no logos."

La bicicletta è tornata scura, e il tavolo, la tazza, la pianta e il telaio della finestra erano ancora nell'inquadratura. La partenza era un JPEG 1024×683, l'output misurava 1024×682 e l'esecuzione ha richiesto 38,0 s. Scrivi ogni volta la lista di ciò che resta: per la struttura dei prompt in generale, vedi la nostra guida ai prompt di GPT Image 2.

Errori e limiti

Due header fanno il lavoro prima che esista qualsiasi pixel: il token bearer e un Idempotency-Key univoco. Se sono corretti, il resto della chiamata è facile da ripetere.

La chiave può arrivare a 255 caratteri, secondo la documentazione verificata il 29 ottobre 2026. Ripetere con lo stesso body è il tentativo sicuro: ricevi l'attività esistente e non viene addebitato nulla di nuovo. Tieni il body sotto 1 MiB, Base64 incluso, quindi ridimensiona o comprimi la partenza prima di inviarla.

Quando un'attività riesce, assets[0].url è un link firmato che dura circa un'ora, secondo la documentazione, quindi scarica subito o interroga di nuovo la stessa attività per un link fresco. I record delle attività restano per 24 ore.

Un header ci ha sorpresi il 29 ottobre 2026: una POST inviata con lo User-Agent predefinito di urllib di Python ha restituito HTTP 403 con il body "error code: 1010" da Cloudflare. La stessa POST con il nostro header User-Agent: omniakey-example/1 ha raggiunto l'API, che ha risposto 400 invalid_request per il body vuoto che abbiamo inviato, e non è stato addebitato nulla. La documentazione nomina solo Authorization e Idempotency-Key, quindi imposta uno User-Agent nel tuo client.

GPT Image 2.5 o GPT Image 2 per lavorare con l'API?

Flare è l'id 2.5 che abbiamo provato. GPT Image 2, nella sua pagina del modello GPT Image 2, usa l'id gpt-image-2. Se uno script produce già ciò che ti serve con quell'id, non c'è motivo di cambiarlo.

Per una foto che deve mantenere la scena mentre un oggetto cambia, Flare su medium è ciò che coprono le nostre esecuzioni del 29 ottobre 2026: tre dimensioni generate e la modifica a 1024×682. Il confronto tra GPT Image 2.5 e GPT Image 2 riporta dimensioni e risultati dello stesso prompt per entrambi i modelli, così scegli con i numeri davanti. Le tariffe attuali sono nella pagina dei prezzi.

Domande frequenti

Quale id del modello devo usare, gpt-image-2.5-flare o gpt-image-2.5-sunburst?

Abbiamo usato Flare in tutte le esecuzioni sopra, e la sua modifica ha conservato la scena che avevamo chiesto di conservare. La pagina del modello elenca Sunburst come secondo id 2.5: parti da Flare e metti Sunburst alla prova sulla tua modifica più difficile prima di passare.

Posso chiedere una dimensione orizzontale come 1536x1024?

Il 29 ottobre 2026 una generazione a 1536x1024 è tornata a 1536×1024. La lista di dimensioni nella documentazione dell'API immagini non include questo valore per il modello, quindi leggi il file e controlla la documentazione prima di farci affidamento in produzione.

Perché la mia modifica è tornata in una dimensione diversa da quella richiesta?

La stessa modifica a 1K è tornata a 1024×682 in un'esecuzione e a 1024×1024 in un'altra, quindi tratta la dimensione richiesta come una richiesta, non come una promessa. Apri il PNG e leggi larghezza e altezza prima di posizionarlo.

Serve un header User-Agent?

Il 29 ottobre 2026 una richiesta con lo User-Agent predefinito di Python ha ricevuto HTTP 403 con l'errore 1010 di Cloudflare. La stessa richiesta con il nostro header User-Agent ha raggiunto l'API, quindi inviane uno.

Quanto durano i link alle immagini?

La documentazione dice che il link firmato dura circa un'ora. Interroga di nuovo l'attività per un link fresco e scarica il file appena l'attività riesce.