Seedream 5.0 Pro API: generare immagini con Python

Basta una POST a https://api.omniakey.com/v1/media/tasks con model su Dola-Seedream-5.0-pro e operation su generate, poi si interroga l'id del task finché lo stato non è succeeded e si scarica assets[0].url. Per impostazione predefinita l'immagine porta l'etichetta "AI generated" nell'angolo. Il 29 ottobre 2026 abbiamo eseguito quella richiesta e una modifica a 1024x1024, e entrambi i file sono tornati come PNG 1024×1024.

Qui sotto trovano posto l'id e le due operazioni, il codice della richiesta eseguito senza modifiche, un elenco delle taglie richieste accanto ai pixel letti in ciascun file, l'etichetta, l'impostazione che la spegne (non eseguita) e i due errori che bloccano una chiamata di creazione. Le due immagini sono quelle prodotte quel giorno.

Quale id di modello usare e quali operazioni esistono

Si usa Dola-Seedream-5.0-pro, l'id della pagina del modello Seedream 5.0 Pro (verificata il 29 ottobre 2026). La pagina elenca due operazioni, testo in immagine e modifica di immagine. Dice anche che generazione e modifica hanno la stessa tariffa e che né la taglia scelta né le immagini di riferimento allegate la aumentano. Le tariffe attuali sono nella pagina dei prezzi.

Prima del prompt, la forma della richiesta dipende da questi campi:

• model: Dola-Seedream-5.0-pro
• operation: generate o edit
• parameters.size: 1K, 1.5K, 2K, oppure widthxheight con una x
• output_format: png o jpeg, e jpeg è il valore predefinito

I campi di taglia e formato stanno dentro parameters. L'output si ferma a 2K: la pagina del modello (verificata il 29 ottobre 2026) non elenca una taglia 4K. Seedream vuole una x minuscola tra i due lati, mentre Qwen e Wan vogliono un asterisco, quindi in un client che chiama entrambi le due forme vanno tenute separate. Le nostre esecuzioni hanno usato la forma widthxheight con 1024x1024 e PNG, mentre le tre taglie sono rimaste fuori.

ByteDance vende lo stesso modello su BytePlus ModelArk con un altro id, dola-seedream-5-0-pro-260628. Quell'id appartiene a BytePlus, quindi una richiesta a OmniaKey vuole l'id qui sopra.

Il codice della richiesta

Lo script qui sotto è quello eseguito il 29 ottobre 2026, senza modifiche: due helper, una chiamata di generazione, una di modifica, solo libreria standard di Python. Legge la chiave da OMNIAKEY_API_KEY e scrive ogni PNG nella cartella da cui lo lanciate. La documentazione dell'API immagini descrive gli stessi tre passaggi.

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

API = "https://api.omniakey.com/v1/media/tasks"
KEY = os.environ["OMNIAKEY_API_KEY"]
MODEL = "Dola-Seedream-5.0-pro"

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 poll(url, attempts=5):
    for attempt in range(attempts):
        try:
            return request("GET", url)
        except urllib.error.HTTPError as err:
            if err.code < 500 or attempt == attempts - 1:
                raise
        except urllib.error.URLError:
            if attempt == attempts - 1:
                raise
        time.sleep(5 * (attempt + 1))

def run_task(body, out_path):
    task = request("POST", API, body, {"Idempotency-Key": str(uuid.uuid4())})["id"]
    print("task", task, flush=True)
    for _ in range(150):
        time.sleep(4)
        state = poll(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: short-lived, 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="1024x1024"):
    body = {
        "model": MODEL,
        "type": "image",
        "operation": "generate",
        "input": {"prompt": prompt},
        "parameters": {"size": size, "output_format": "png"},
    }
    return run_task(body, out_path)

def edit_image(source_path, prompt, out_path, size="1024x1024"):
    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, "output_format": "png"},
    }
    return run_task(body, out_path)

if __name__ == "__main__":
    task = generate_image(
        "A glass bottle of cold-pressed orange juice on a pale stone counter, morning light from the left, "
        "a single orange slice beside it, shallow depth of field, no text, no logos.",
        "juice-bottle.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)

I tre passaggi stanno dentro run_task: crea il task con una chiave di idempotenza nuova, interroga l'URL del task finché lo stato non esce da queued e processing, poi scarica l'URL del primo asset. La chiamata di creazione risponde HTTP 202 con un id che inizia per task_, e lo stato parte da queued (documentazione, verificata il 29 ottobre 2026). Un task che finisce in failed solleva l'errore della risposta, così il motivo compare direttamente nel terminale.

Le taglie e i formati eseguiti, e cosa è tornato

Le due esecuzioni hanno chiesto la stessa stringa di taglia e lo stesso formato, e entrambi i file sono tornati come PNG 1024×1024.

• Generazione — Taglia richiesta: 1024x1024; Pixel nel file: 1024×1024; Formato: PNG; Data: 2026-10-29
• Modifica — Taglia richiesta: 1024x1024; Pixel nel file: 1024×1024; Formato: PNG; Data: 2026-10-29

La dimensione in pixel va letta nel file scaricato. La stringa di taglia è ciò che avete chiesto; il file è ciò che avete ricevuto. Abbiamo aperto ogni PNG, letto larghezza e altezza e guardato l'immagine accanto al prompt che l'ha prodotta.

La modifica è l'esecuzione più interessante. Abbiamo inviato un JPEG 1024×683 di una vetrina di caffè e una sola istruzione, ed è tornata un'immagine quadrata. La bicicletta ora è scura, il tavolo, la tazza e la pianta sono ancora nel fotogramma, e poiché l'output è quadrato, la vetrina e il bordo del tavolo risultano inquadrati diversamente dalla sorgente.

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.

L'etichetta e come spegnerla

Ogni output porta l'etichetta "AI generated" nell'angolo, a meno che watermark non sia impostato a false nei parameters, secondo la pagina del modello (verificata il 29 ottobre 2026). La pagina mette l'etichetta nell'angolo in basso a destra, ed è lì che si trova nell'output predefinito qui sotto: tenue e piccola. Se watermark resta fuori dalla richiesta, l'etichetta c'è.

A glass bottle of cold-pressed orange juice on a pale stone counter, morning light from the left, a single orange slice beside it, shallow depth of field, no text, no logos.

Ecco quell'output, prodotto con le impostazioni predefinite:

L'impostazione con watermark false non è stata eseguita: il limite di spesa per esecuzione dello strumento del blog ha fermato la chiamata prima dell'invio.

Errori e limiti

Due header decidono se una chiamata di creazione passa: il bearer token e un Idempotency-Key.

La stessa chiave con lo stesso body è il retry che serve: torna il task esistente e non viene addebitato nulla di nuovo. La stessa chiave con prompt o taglia modificati restituisce 409, quindi create una chiave nuova per ogni richiesta nuova. La chiave può arrivare a 255 caratteri (documentazione, verificata il 29 ottobre 2026).

Tenete il body della richiesta sotto 1 MiB, immagine Base64 inclusa, e ridimensionate una foto sorgente grande prima di inviarla. Quando un task riesce, l'URL di download nella risposta è un link firmato che dura circa un'ora, secondo la documentazione, quindi scaricate il file subito o interrogate di nuovo il task per un link fresco.

Un header ci ha sorpresi il 29 ottobre 2026. Una POST inviata con lo User-Agent predefinito di urllib di Python è tornata HTTP 403 con il body error code: 1010 di Cloudflare. Il nostro header User-Agent è arrivato all'API e non è stato addebitato nulla.

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

Decide il lavoro. Nella nostra modifica Seedream 5.0 Pro ha cambiato l'oggetto che avevamo indicato, la bicicletta, e ha mantenuto gran parte della scena, anche se l'inquadratura è cambiata; le nostre due esecuzioni sono state una vetrina di caffè e una bottiglia di succo. La chiamata è un solo body con operation su generate o edit, e la sorgente può essere un URL pubblico o Base64 inline (documentazione, verificata il 29 ottobre 2026).

Per vedere il risultato dello stesso prompt accanto a GPT Image 2, il confronto Seedream 5.0 Pro vs GPT Image 2 mostra i due output di un unico prompt. Per la stessa forma genera-e-modifica su un altro modello, il tutorial dell'API GPT Image 2.5 segue la richiesta e le taglie. Eseguite il vostro prompt più difficile sul candidato prima di spostare una pipeline, poi controllate le tariffe.

FAQ

Quale id di modello invio all'API?

Dola-Seedream-5.0-pro, l'id della richiesta di esempio nella pagina del modello (verificata il 29 ottobre 2026). Il dola-seedream-5-0-pro-260628 di ByteDance appartiene a BytePlus ModelArk, e OmniaKey vuole l'id qui sopra.

Perché la mia immagine ha l'etichetta "AI generated"?

Ogni output di Seedream 5.0 Pro porta l'etichetta nell'angolo in basso a destra, a meno che watermark non sia impostato a false, secondo la pagina del modello (verificata il 29 ottobre 2026). La nostra esecuzione con le impostazioni predefinite del 29 ottobre 2026 la conteneva.

Quali taglie accetta l'API?

Le taglie 1K, 1.5K e 2K, oppure la forma widthxheight con una x minuscola tra i due lati (pagina del modello, verificata il 29 ottobre 2026). L'output si ferma a 2K, e le nostre due esecuzioni hanno chiesto 1024x1024.

Posso avere PNG invece di JPEG?

Sì. output_format accetta png o jpeg, e JPEG è il valore predefinito (documentazione, verificata il 29 ottobre 2026). Abbiamo usato PNG in entrambe le esecuzioni e abbiamo ricevuto PNG.

Posso modificare un'immagine esistente con Seedream?

Sì: inviate operation su edit con il prompt e l'immagine sorgente, come Base64 inline con il mime type oppure come URL pubblico. La modifica della vetrina di caffè è nella sezione sulle taglie qui sopra.