Tutorial API Seedream 5.5: codice Python, prezzi e risultati reali

Per chiamare l’API Seedream 5.5, invia un POST a https://api.seedrouter.ai/v1/images/generations con "model": "seedream-5-5" e un prompt, conserva l’id dell’attività restituito e interroga GET /v1/tasks/{id} finché lo stato non diventa completed. L’attività completata contiene gli URL delle immagini. La stessa richiesta permette anche di modificare con fino a 10 immagini di riferimento, creare PNG con sfondo trasparente e scomporre un’immagine in livelli trasparenti.

ByteDance ha lanciato Seedream 5.5 il 9 novembre 2026, con tre novità principali: modifiche più stabili su molti passaggi, output trasparente nativo e immagini più realistiche con testo piccolo più nitido.^[1] Il giorno dopo l’abbiamo eseguito tre volte su SeedRouter. Questo tutorial si basa su quelle prove: il codice inviato, i risultati ricevuti, i tempi e i costi. Ogni campo è elencato nella documentazione API di Seedream 5.5 e il Playground è sulla pagina del modello.

Cosa ti serve prima della prima chiamata all’API Seedream 5.5?

Due cose: una chiave API e l’ID modello. Non c’è nulla da scaricare. ByteDance non ha pubblicato i pesi di Seedream 5.5, quindi il modello funziona tramite un’API ospitata e il tuo codice invia solo JSON.

Crea una chiave in chiavi API e tienila in una variabile d’ambiente sul tuo server, mai nel codice del browser:

export SEEDROUTER_API_KEY="your-key"
pip install requests

L’ID modello è seedream-5-5. Un solo ID copre la generazione da testo, la modifica e la scomposizione in livelli; i campi della richiesta decidono quale operazione eseguire. Un nuovo account parte con un piccolo saldo gratuito, sufficiente per qualche immagine di prova a 1K prima di ricaricare.

Come si genera un’immagine con Python?

L’invio risponde subito con un’attività, non con l’immagine. Questo script invia un prompt, interroga ogni 10 secondi, si ferma dopo 15 minuti e salva ogni immagine ricevuta.

import os
import time
import requests

API = "https://api.seedrouter.ai/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}


def submit(body):
    r = requests.post(f"{API}/images/generations", headers=HEADERS, json=body, timeout=60)
    r.raise_for_status()
    return r.json()["id"]


def wait(task_id, limit=900):
    deadline = time.time() + limit
    while time.time() < deadline:
        r = requests.get(f"{API}/tasks/{task_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        task = r.json()
        if task["status"] in ("completed", "failed"):
            return task
        time.sleep(10)
    raise TimeoutError(f"{task_id} is still running; poll it again later")


task_id = submit({
    "model": "seedream-5-5",
    "prompt": "A ceramic teapot shaped like a sleeping fox on a linen tablecloth, "
              "soft morning window light, shallow depth of field. No text.",
    "size": "1K",
})
task = wait(task_id)
if task["status"] == "failed":
    raise RuntimeError(task["error"]["message"])

for i, image in enumerate(task["output"]["data"]):
    data = requests.get(image["url"], timeout=60).content
    with open(f"seedream-{i}.{image['output_format']}", "wb") as f:
        f.write(data)
    print(image["size"], image["url"])

Questa è la nostra prima prova. Si è conclusa in 47 secondi e ha restituito un PNG da 1248 × 832.

Due abitudini di questo ciclo contano in produzione. Se il polling va in timeout, conserva l’ID attività e controlla di nuovo; l’immagine potrebbe essere ancora in arrivo. Non inviare la richiesta una seconda volta per «riprovare», perché crei una seconda attività e un secondo addebito.

Quali campi della richiesta contano?

Alla maggior parte delle richieste bastano model, prompt e size. I campi che imposterai più spesso, con i relativi valori predefiniti:

L’output più grande è 2K. La nostra modifica in 16:9 a 2K ha restituito 2560 × 1440 e le dimensioni esatte possono arrivare a 4.624.220 pixel totali. Non c’è un campo per le proporzioni: per una forma fissa, invia dimensioni esatte in pixel. Non esistono fasce 3K o 4K, quindi se ti serve un file più grande dovrai ingrandirlo dopo. La documentazione API elenca ogni campo. I campi non elencati vengono ignorati anziché rifiutati: un seed, uno style o un n rimasto da un’altra API di immagini non fa fallire la richiesta e non ha alcun effetto. Una richiesta crea un’immagine.

Come si modifica un’immagine con immagini di riferimento?

Inserisci la sorgente in image e indica nel prompt cosa cambiare e cosa conservare. La nostra seconda prova ha trasformato una foto al sole di un pittore sul ballatoio di un faro in una notte d’inverno:

task_id = submit({
    "model": "seedream-5-5",
    "prompt": "Turn this scene into a snowy winter night with warm light from "
              "the lighthouse windows, keep the composition",
    "image": "https://static.seedrouter.ai/media/landing/models/seedream-5-5/v1/lighthouse-source.webp",
    "size": "2560x1440",
})

Ha richiesto 40 secondi e ha restituito un PNG da 2560 × 1440. Il pittore, la posa, il pennello, la corda arrotolata, entrambi i barattoli di vernice e la ringhiera sono rimasti tutti al loro posto. Sono stati aggiunti neve che cade, neve sul ballatoio e sulle sue spalle, un cielo scuro e finestre illuminate sopra la fascia rossa.

Con più riferimenti, citali in base all’ordine nell’elenco («la giacca dell’immagine 2»). Ogni immagine di riferimento viene addebitata, fin dalla prima, quindi invia solo le immagini necessarie alla modifica.

Per questa versione ByteDance sostiene soprattutto che le aree non modificate restano identiche a livello di pixel tra una modifica e l’altra, con test su 100 passaggi consecutivi.^[1] Tramite API, una modifica su più passaggi è un ciclo: prendi l’URL di un’attività completata e passalo come image nella richiesta successiva. Non abbiamo ancora eseguito una lunga catena di prove, quindi non possiamo confermare il dato dei 100 passaggi. Ricorda che ogni passaggio è una nuova attività e paga la propria immagine di riferimento.

Come si ottiene un PNG trasparente?

Imposta background su transparent e mantieni output_format su png. Funziona da un solo prompt o con riferimenti:

task_id = submit({
    "model": "seedream-5-5",
    "prompt": "A glossy red enamel pin shaped like a cherry, product cutout",
    "background": "transparent",
    "size": "1K",
})

transparent con jpeg viene rifiutato prima della creazione di un’attività, perché JPEG non ha canale alfa. ByteDance descrive questa funzione come output RGBA nativo con trasparenza completa e parziale e bordi resi con cura, per cui la risorsa non richiede una rimozione separata dello sfondo.^[1]

Come si scompone un’immagine in livelli con l’API?

Invia esattamente un’immagine con layer_decomposition: true. La nostra terza prova ha scomposto un poster jazz con il riconoscimento del testo attivo e un massimo di quattro immagini restituite:

task_id = submit({
    "model": "seedream-5-5",
    "image": "https://static.seedrouter.ai/media/landing/models/seedream-5-5/v1/poster-source.webp",
    "layer_decomposition": True,
    "size": "1K",
    "layer_decomposition_options": {"max_images": 4, "text_recognition": True},
})

Ha richiesto 39 secondi e ha restituito quattro immagini: l’immagine di fondo e tre livelli trasparenti.

I due livelli di testo sono stati restituiti con le parole riconosciute. Il text_recognition del livello del titolo conteneva "BLUE TIDE\nSESSIONS", con il font stimato come HTF Didot e il colore #122C4D, mentre il livello della didascalia conteneva "LIVE JAZZ · PIER 7 HALL · SATURDAY 9 PM". Ogni riga ha il proprio riquadro di delimitazione e stile, così puoi riscrivere il testo con il tuo font nella stessa posizione.

Tre cose da sapere prima di affidarti al risultato:

• I file dei livelli sono più grandi dei loro riquadri. Il fattore è diverso per ciascun livello: 1,74× per il titolo, 1,08× per l’illustrazione e 2,59× per la didascalia. Ridimensiona ogni PNG al suo bounding_box.absolute prima di posizionarlo, poi sovrapponi i livelli in ordine crescente di z_index.
• max_images è un limite massimo e un limite basso unisce le parti. Con quattro posti disponibili, il modello ha inserito il sassofonista, le onde e il sole color corallo in un solo livello. Lascia spazio per il numero di elementi che ti aspetti.
• Un elemento può comparire due volte. Il sole color corallo era nel livello illustrato ed era rimasto anche sull’immagine di fondo. Controlla l’immagine di fondo prima di spostare un livello.

Quanto costa l’API Seedream 5.5?

Paghi per immagine, in base alle dimensioni di ciascuna, più ogni immagine di riferimento. Le immagini fino a 2,61 milioni di pixel (1K e 1.5K) rientrano nella fascia inferiore; 2K e tutto ciò che è più grande nella fascia superiore. La scomposizione in livelli addebita l’immagine di fondo e ogni livello in base alle rispettive dimensioni. Le attività fallite non vengono addebitate.

Le nostre tre prove del 10 novembre 2026 e cosa è stato addebitato per ciascuna:

Moltiplica queste unità per i prezzi nella tabella qui sopra per ottenere il conto. La scomposizione merita attenzione: è costata quattro immagini, non una, perché vengono addebitati l’immagine di fondo e ogni livello.

Durante l’esecuzione, una scomposizione in livelli riserva più di quanto addebita. Quando l’attività viene accettata, viene riservato il saldo necessario per max_images immagini, 30 se lo ometti, con auto conteggiato nella fascia superiore. Al termine dell’attività vengono addebitate le immagini ricevute e il resto viene sbloccato. Una scomposizione senza max_images e senza size richiede quindi un saldo sufficiente per 30 immagini nella fascia superiore più l’immagine di input per poter partire, anche se restituisce quattro immagini. Imposta max_images vicino al numero di parti che ti aspetti e scegli una fascia, come nella nostra terza prova (quattro richieste, quattro restituite), e l’importo riservato resta vicino all’addebito.

Quali errori devi prevedere?

I riferimenti devono essere URL HTTP(S) pubblici. I data URI in base64 vengono rifiutati, quindi carica prima il file nel tuo storage. Sono accettati JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC e HEIF, fino a 30 MB ciascuno. L’elenco completo dei codici è nel catalogo degli errori.

Domande frequenti

Esiste Seedream 5.5 Pro?

Non ancora. Il post di lancio di ByteDance dice "A Pro version of the Seedream 5.5 series will follow" (seguirà una versione Pro della serie) e non indica una data.^[1] Oggi l’API ha un solo modello, seedream-5-5. Il modello Pro della generazione precedente è ancora disponibile come Seedream 5.0 Pro.

L’API Seedream 5.5 è gratis?

No. Si paga per immagine da un saldo prepagato, senza abbonamento. Il piccolo saldo gratuito di un nuovo account copre qualche immagine a 1K, quindi puoi eseguire lo script qui sopra prima di ricaricare.

Posso scaricare Seedream 5.5?

No. ByteDance non ha pubblicato i pesi del modello, quindi non esiste un file da eseguire in locale. Lo usi tramite un’API come questa.

Quante immagini di riferimento posso inviare?

Fino a 10 in image. La scomposizione in livelli ne richiede esattamente una.

Quanto tempo ci vuole per una richiesta?

Le nostre tre prove hanno richiesto da 39 a 47 secondi. Le scomposizioni che restituiscono molti livelli possono richiedere diversi minuti, per questo lo script qui sopra interroga per un massimo di 15 minuti.

Riferimenti

1. ByteDance Seed. More Realistic Images, More Stable Editing Across 100 Rounds | Introducing Seedream 5.5. 9 novembre 2026. Consultato l’11 novembre 2026 su seed.bytedance.com.
2. SeedRouter. Documentazione API di Seedream 5.5. /docs/seedream-5-5.