
Tutorial API Seedream 5.5: genera, modifica e separa immagini
Chiama Seedream 5.5 una volta, segui l’attività, modifica con riferimenti e crea PNG trasparenti o livelli. Verifica dimensioni e prezzi aggiornati.
Seedream 5.5 restituisce un ID attività prima di restituire un'immagine. Invia la richiesta una sola volta, salva l'ID ed esegui il polling per il risultato finito. La generazione produce un'immagine; la scomposizione può produrre una base e livelli trasparenti. Entrambi i flussi usano model: "seedream-5-5", ma le regole di input differiscono. 1
Questo tutorial parte da un brief per una teiera in ceramica, passa alla generazione e a una modifica mirata, poi mostra come separare un poster esistente in livelli. Il Playground Seedream 5.5 espone gli stessi controlli della richiesta. Puoi esaminare il JSON lì prima di aggiungerlo a un'applicazione.
La specifica è stata verificata il 12 novembre 2026. I nostri controlli di integrazione hanno riprodotto 34 casi di richiesta e risposta, incluse impostazioni di trasparenza incompatibili, limiti dei livelli e output completati senza dimensioni utilizzabili. Questi controlli convalidano la gestione delle richieste e gli input contabili; non sono un benchmark di velocità di generazione o qualità delle immagini. Le immagini sotto sono esempi Seedream 5.5 esistenti del 10 novembre.
Parti da una chiave e una piccola richiesta
Crea una chiave in Chiavi API, conservala sul tuo server e usa https://api.wanapi.app come URL di base. La tua chiave Wan API esistente funziona con i modelli e gruppi disponibili. Non c'è una chiave separata da acquistare o selezionare per questo modello di immagini.
Salva questo contenuto come generate.json:
{
"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",
"output_format": "png",
"content_filter": true
}Imposta WAN_API_KEY nell'ambiente del server, poi invia una sola volta:
curl --fail-with-body --retry 0 --max-time 90 \
https://api.wanapi.app/seedream55/v1/images/generations \
-H "Authorization: Bearer $WAN_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @generate.json \
-o submitted.jsonUna risposta riuscita contiene id, model e uno stato di elaborazione. Conserva l'intero file submitted.json. Non interpretare l'assenza di un URL immagine come una generazione fallita: questa risposta conferma l'attività. Se la connessione si interrompe prima di ricevere un ID, controlla i log delle attività prima di tentare un altro POST. Una risposta incerta non autorizza a creare di nuovo la stessa attività a pagamento.
Per questa prima richiesta abbiamo selezionato esplicitamente 1K. Omettendo size, la generazione usa 2K per impostazione predefinita. PNG è il formato predefinito, la filigrana è disattivata e il controllo dei contenuti è attivo. Chi chiama l'API pubblica può modificare esplicitamente content_filter; il Playground mantiene il controllo attivo per gli account ordinari. 1
Esegui il polling dell'ID salvato, anche dopo un aggiornamento
L'URL di polling è GET /seedream55/v1/tasks/{id}. Una risposta completata contiene le immagini in output.data; non usa la struttura di risposta dell'API Images sincrona. Ogni voce ha un URL e le dimensioni effettive in pixel.
Questo script Python legge la risposta salvata ed esegue il polling per un massimo di dieci minuti. Invia solo richieste GET, quindi rieseguirlo continua l'attività esistente:
import json
import os
import time
import urllib.error
import urllib.request
from pathlib import Path
saved = json.loads(Path("submitted.json").read_text())
task_id = saved["id"]
url = f"https://api.wanapi.app/seedream55/v1/tasks/{task_id}"
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
request = urllib.request.Request(
url,
headers={"Authorization": f"Bearer {os.environ['WAN_API_KEY']}"},
)
try:
with urllib.request.urlopen(request, timeout=30) as response:
task = json.load(response)
except urllib.error.HTTPError as error:
if error.code != 429 and error.code < 500:
raise
time.sleep(5)
continue
except (urllib.error.URLError, TimeoutError):
time.sleep(5)
continue
if task["id"] != task_id:
raise RuntimeError("Unexpected task identity")
if task["status"] == "failed":
raise RuntimeError(task.get("error", {}).get("message", "Task failed"))
if task["status"] == "completed":
Path("result.json").write_text(json.dumps(task, indent=2))
for index, image in enumerate(task["output"]["data"], start=1):
print(index, image["size"], image["url"])
break
time.sleep(5)
else:
print("Still waiting. Keep submitted.json and resume this GET later.")Il limite di dieci minuti appartiene a questo client di esempio. Non annulla un'attività né dimostra che la generazione sia fallita. Non abbiamo stabilito un intervallo di latenza misurato per questa integrazione: prevedi quindi uno stato di attesa senza promettere un numero fisso di secondi. Salva i file scaricati quando sono pronti; non trattare gli URL dei risultati come archiviazione permanente delle risorse.

Questo esempio misura 1248 × 832 pixel. L'opzione 1K indica una fascia di risoluzione, non garantisce che entrambe le dimensioni siano 1024. Leggi size dal risultato quando il layout o il calcolo dei costi richiede dimensioni esatte.
Cambia la scena indicando cosa deve restare
Per una modifica, aggiungi image con un URL HTTP(S) pubblico. Può essere una foto sorgente ospitata da te o un file generato che hai scaricato e ospitato autonomamente. I riferimenti non possono essere caricamenti di file, Base64 o URI data. Devono restare accessibili durante l'elaborazione della richiesta. I formati di input supportati e i limiti dei media sono elencati nella documentazione API. 1
{
"model": "seedream-5-5",
"image": "https://your-public-host.example/fox-teapot.png",
"prompt": "Keep the fox teapot, its curled tail, ceramic texture and camera angle. Replace the linen tablecloth with dark walnut wood. Keep the soft light coming from the left. No text.",
"size": "1K"
}L'URL sopra è un segnaposto: sostituiscilo con la tua immagine accessibile. Invialo come attività di modifica separata e intenzionale e salva la risposta con un nuovo nome di file. Il modello non ricorda l'attività precedente: devi inviare l'immagine da modificare.
Per più riferimenti, image accetta un array di fino a dieci URL. Assegna a ciascuna immagine un ruolo nel prompt, per esempio il prodotto della prima e l'ambientazione della seconda. Parti dal più piccolo insieme utile. Se il risultato cambia un dettaglio importante, meno riferimenti facilitano l'identificazione dell'istruzione o sorgente che ha introdotto il cambiamento.
La conservazione è un'istruzione, non un blocco dei pixel. Dopo ogni modifica confronta sagoma del prodotto, etichette e angolazione della camera con l'originale. Per i poster, riporta tra virgolette il titolo esatto e controlla punteggiatura, nomi e date alle dimensioni di visualizzazione previste. Le scritte piccole o stilizzate possono comunque richiedere correzioni manuali; questa guida non promette un tasso di accuratezza misurato per alcuna lingua.
Per uno scontorno, aggiungi "background": "transparent" e mantieni "output_format": "png". JPEG non può contenere quel canale alfa. La trasparenza è disponibile per generazione e modifica; la modalità livelli segue le proprie regole riportate sotto.
Separa un poster in livelli riutilizzabili
La scomposizione in livelli richiede esattamente un'immagine. Il prompt è facoltativo: omettilo per lasciare scegliere gli elementi al modello oppure indica le parti da separare. Parti da un limite di output basso mentre valuti un progetto:
{
"model": "seedream-5-5",
"image": "https://your-public-host.example/poster.png",
"size": "1K",
"layer_decomposition": true,
"layer_decomposition_options": {
"max_images": 4,
"text_recognition": true
},
"output_format": "png"
}max_images conta anche l'immagine di base. Quattro consente quindi la base più fino a tre livelli. Il limite consentito è 2–100, con valore predefinito 30, e il modello può restituire meno immagini. Non inviare background in questa modalità, nemmeno come auto. I livelli separati sono già PNG trasparenti; output_format controlla l'immagine di base. 1

Questa anteprima esistente combina il poster sorgente e gli elementi trasparenti restituiti. Aiuta a capire la separazione, ma non garantisce che ogni poster produca lo stesso numero di livelli o contorni puliti.
Esamina i metadati facoltativi insieme a ciascun risultato:
| Campo | Come usarlo |
|---|---|
z_index | Colloca i valori più alti sopra quelli più bassi. |
bounding_box.absolute | Posiziona il livello usando sinistra, alto, destra e basso in pixel dell'immagine di base. |
bounding_box.normalized | Le coordinate corrispondenti su una scala 0–1000. |
name, description | Identifica l'elemento separato dal modello. |
text_recognition | Leggi testo riconosciuto, righe e informazioni di stile disponibili. |
Conserva il JSON completo del risultato, non solo gli URL. Un livello può avere dimensioni diverse rispetto alla sua collocazione sulla tela di base. Usa il riquadro di delimitazione per ricostruire la composizione e controlla visivamente il risultato. I font suggeriti sono stime; i metadati OCR non garantiscono il font originale né un file PSD pronto. Scritte artistiche, elementi sovrapposti e testo escluso dal prompt possono produrre risultati incompleti.
Scegli le dimensioni prima di confrontare i costi
La generazione supporta 1K, 1.5K e 2K, oltre a dimensioni esatte WIDTHxHEIGHT entro 921.600–4.624.220 pixel totali e un rapporto d'aspetto da 1:16 a 16:1. La modalità livelli accetta queste dimensioni predefinite o auto, ma non dimensioni esatte. Questa specifica non espone opzioni 3K o 4K, il batch n, un seed né una modalità fast di ottimizzazione del prompt. Non trasferire parametri da un'altra versione Seedream senza verificarli. 1
Le tariffe attuali sono mostrate qui dalla stessa fonte dei prezzi del Playground:
I prezzi non sono attualmente disponibili. Aggiorna la pagina per riprovare.
Le tariffe si aggiornano automaticamente. Una chiave API funziona con tutti i modelli e gruppi.
Indichiamo con L la tariffa di output fino a 2,61 milioni di pixel, con H quella sopra tale soglia e con R la tariffa per immagine di riferimento. Una generazione 1K senza riferimenti costa L; una modifica con un riferimento costa L + R. Sia 1K sia 1.5K usano la tariffa di output inferiore. Ogni riferimento viene addebitato, incluso il primo. 2
Una richiesta di livelli 1K da quattro immagini stima 4L + R. Se restituisce solo la base e due livelli, ciascuno nella fascia inferiore, il costo finale è 3L + R. Con dimensioni di output miste, conta ogni immagine separatamente: due immagini nella fascia inferiore e una più grande costano 2L + H + R. La base è un'immagine di output e non va esclusa dal conteggio.
La prenotazione iniziale copre il limite scelto. I fondi inutilizzati vengono rilasciati dopo la contabilizzazione degli output effettivi e un'attività fallita viene rimborsata. Nei nostri test contabili, riprodurre la stessa risposta completata non ha modificato il saldo una seconda volta. Abbiamo anche verificato che un completamento privo di tutti i dati richiesti sull'utilizzo delle immagini restasse non contabilizzato, senza trattare quantità stimate come output osservato.
Quando una richiesta o un risultato richiede attenzione
Un errore di convalida indica di solito un'incompatibilità con la modalità: più riferimenti nella modalità livelli, JPEG trasparente, dimensioni non supportate o opzioni dei livelli in una richiesta di generazione. Correggi la richiesta prima di creare una nuova attività. Un errore temporaneo di polling è diverso: conserva l'ID esistente e riprova il GET. Sono decisioni separate; riunirle in un gestore generico che riprova tutto rischia di duplicare la generazione a pagamento.
Per una modifica insoddisfacente, confronta un cambiamento alla volta con l'originale. Un output più grande non dimostra che il modello abbia mantenuto un'etichetta o riprodotto correttamente un titolo. Per i livelli, controlla bordi e metadati mancanti prima di importare il risultato in un progetto di produzione. Il controllo dei contenuti resta attivo per impostazione predefinita; un rifiuto dei contenuti non dovrebbe attivare un reinvio automatico con il controllo disattivato.
Seedream 5.5 è adatto ai flussi che richiedono generazione, modifiche con riferimenti o elementi grafici separabili secondo questa specifica. Seedream 5.0 Pro è un modello distinto con valori predefiniti e limiti diversi. Non abbiamo eseguito un confronto controllato che consenta di affermare che uno sia sempre migliore. Questa guida non dichiara neppure la disponibilità di un distinto “5.5 Pro” né promette generazione gratuita. Consulta la pagina del modello per Playground e prezzo attuali oppure usa il documento OpenAPI per integrare la convalida delle richieste nella tua applicazione.
Riferimenti
- Documentazione API Seedream 5.5: campi delle richieste, valori predefiniti, input URL, risposte asincrone e metadati dei livelli. Specifica verificata il 12 novembre 2026.
- Prezzi aggiornati di Seedream 5.5: fasce di pixel di output e tariffe delle immagini di riferimento.
Categorie
Altri articoli

Seedream 5.0 Pro: cosa restituisce la separazione in livelli e come viene addebitata
Come separare immagini in livelli con l'API Seedream 5.0 Pro: regole di input, dimensioni, dati restituiti e costi per livello da verificare prima.


Guida all'API Wan 3.0: modelli, input e primo video
Confronta gli input API e le specifiche di output di Wan 3.0, Wan 3.0 Prime, Wan 3.0 Pro e Wan 3.0 Prime Pro e prepara il tuo primo test video.


Seedance 2.5 vs Seedance 2.0: quale scegliere per la tua scena?
Confronta durata, limiti dei riferimenti e impostazioni degli esempi di Seedance 2.5 e 2.0. Prepara un test senza presumere un vincitore per qualità o velocità.

Novità di Wan API
Aggiornamenti sul servizio e novità sui modelli
Iscriviti per ricevere novità sui modelli, aggiornamenti sul servizio e informazioni sull'integrazione API.