Seedream 4.5: guida completa con Python

BytePlus ha appena rilasciato il suo ultimo modello di generazione di immagini, Seedream 4.5. Come divisione tecnologica enterprise di ByteDance, l'azienda porta funzionalità di IA avanzate alle imprese di tutto il mondo, facendo leva sull'innovazione alla base di piattaforme come TikTok.

In questo articolo ti insegnerò a usare Seedream 4.5 con Python integrandolo tramite la sua API per generare immagini in modo programmatico. 

Ti consiglio di seguire il corso Generative AI Concepts come ottimo introduttivo sulla tecnologia dietro modelli di generazione di immagini come Seedream. Se ti interessano anche altri modelli di generazione di immagini, dai un'occhiata alla nostra guida su Nano Banana 2 di Google.

Cos'è Seedream 4.5

Seedream 4.5 è l'ultima iterazione del modello di generazione di immagini IA di BytePlus.

L'ultimo rilascio migliora la coerenza del soggetto, affina i dettagli del testo di piccole dimensioni e ottimizza il blending multi-immagine. Presenta anche una comprensione più robusta delle istruzioni, un miglior ragionamento spaziale e un'inferenza logica più avanzata.

Il modello può inoltre produrre immagini 4K di alta qualità, un miglioramento più che gradito dato che i modelli concorrenti spesso faticano a generare immagini ad alta risoluzione. Anche i costi sono competitivi, con generazioni disponibili a soli 4 centesimi per immagine.

Dai un'occhiata anche al nostro articolo sul nuovo modello di generazione video di ByteDance, Seedance 2.0.

Configurazione dell'API di Seedream 4.5

Senza ulteriori indugi, cominciamo con l'API di Seedream 4.5.

Creazione di una chiave API

Per usare Seedream 4.5 con Python tramite la loro API, dobbiamo prima creare una chiave API.

1. Vai sul loro sito ufficiale, clicca il pulsante Get API in basso a destra ed esegui l'accesso.

2. Una volta effettuato l'accesso, in alto a destra troverai un pulsante Access API. Cliccalo e crea la chiave API. Creare una chiave API richiede la verifica del numero di telefono e l'inserimento delle informazioni di fatturazione. Non si tratta però di un abbonamento, quindi non ci saranno addebiti mensili: pagheremo solo le richieste API.

3. Crea un file chiamato .env nella stessa cartella in cui scriviamo il codice Python e incolla al suo interno la chiave con il seguente formato:

ARK_API_KEY=<paste_key_here>

Prima di poter usare il modello, assicurati anche di attivarlo nella console BytePlus ModelArk. Questo va fatto separatamente dalla chiave API. Per farlo:

1. Vai su Model activation nella barra laterale sinistra.

2. Al centro, scegli Media come categoria corretta del modello.

3. Clicca su Activate sulla destra, nella riga del modello ByteDance-Seedream-4.5.

4. Conferma nella finestra che si apre.

Installazione delle dipendenze Python

Per interagire con l'API di Seedream 4.5, installiamo alcuni pacchetti Python:

• byteplussdkarkruntime: Il pacchetto Python ufficiale che ci permette di effettuare richieste API a Seedream 4.5, parte dell'SDK Python di BytePlus.

• Alcuni pacchetti di supporto per caricare la chiave API dal file .env, effettuare richieste HTTP asincrone e validare le impostazioni.

Installiamo questi pacchetti con il comando:

pip install byteplus-python-sdk-v2 python-dotenv httpx requests typing_extensions pydantic

Generare immagini con Seedream 4.5

Iniziamo imparando a generare un'immagine a partire da un prompt testuale. Se hai letto gli altri nostri tutorial sulle API di IA in Python, come quelli su GPT-Image-1 o Grok Imagine, probabilmente conosci già il flusso tipico:

1. Importare i pacchetti.

2. Caricare la chiave API dal file .env.

3. Creare un client usando il pacchetto API ufficiale.

4. Inviare la richiesta API.

Seedream 4.5 funziona esattamente allo stesso modo. Ecco uno script di esempio per generare un'immagine.

# 1. Import the necessary packages
from dotenv import load_dotenv
from byteplussdkarkruntime import Ark 
import os
# 2. Load the API key
load_dotenv()
# 3. Create the client
client = Ark(
    base_url="https://ark.ap-southeast.bytepluses.com/api/v3", 
    api_key=os.getenv("ARK_API_KEY"), 
)
# 4. Send the API request
prompt = """
Photorealistic anthropomorphic animals hanging out in a coffee shop with no humans.
"""
 
imagesResponse = client.images.generate( 
    model="seedream-4-5-251128",
    prompt=prompt,
    watermark=False,
)
 
image_url = imagesResponse.data[0].url
print(image_url)

In questo esempio specifico, il prompt usato è stato:

Photorealistic anthropomorphic animals hanging out in a coffee shop with no humans.

Ecco cosa ha generato il modello:

Scaricare l'immagine generata

Lo script sopra mostrerà l'URL dell'immagine generata nel terminale. Non è il flusso più comodo. Un'alternativa migliore è creare una funzione che scarichi l'immagine generata nella nostra cartella locale.

import requests
from urllib.parse import urlparse
import os
def download_image(url):
    try:
        response = requests.get(url, stream=True)
        response.raise_for_status()
        parsed_url = urlparse(url)
        filename = os.path.basename(parsed_url.path)
        if not filename:
            filename = "downloaded_image"
        with open(filename, "wb") as f:
            for chunk in response.iter_content(1024):
                f.write(chunk)
        print(f"Image saved to: {filename}")
    except Exception as e:
        print(f"Error downloading image: {e}")

Ti consiglio di creare un nuovo script chiamato utils.py e inserirvi questa funzione. Poi, nello script che genera l'immagine, aggiungiamo il seguente codice per scaricarla:

import utils
utils.download_image(image_url)

Specificare la dimensione dell'immagine

Negli esempi precedenti abbiamo usato i parametri predefiniti di Seedream 4.5, tranne il watermark, che abbiamo impostato su False per nasconderlo.

Seedream 4.5 offre due modi per specificare le dimensioni dell'immagine in output usando il parametro size.

Il primo modo è specificare la risoluzione dell'immagine generata impostando size su "2K" o "4K" e descrivere nel prompt, in linguaggio naturale, il rapporto d'aspetto, la forma o lo scopo, lasciando che sia il modello a determinare larghezza e altezza. Il valore predefinito è "2K".

Ecco un esempio:

prompt = """
Portait Instagram image to be used to promote travel to Tokyo, Japan.
"""
 
imagesResponse = client.images.generate( 
    model="seedream-4-5-251128",
    prompt=prompt,
    size="4K",
    watermark=False,
)

In alternativa, possiamo specificare la dimensione dell'immagine in pixel con una stringa come "3750x1250", ma ci sono due regole da rispettare:

1. I pixel totali (larghezza × altezza) devono essere tra 3,6 milioni e 16,7 milioni.
2. Il rapporto d'aspetto (larghezza ÷ altezza) deve essere tra 1/16 e 16.

Se è soddisfatta solo una delle due regole, la dimensione non è valida. Per evitare questi calcoli, consiglio di usare il metodo della risoluzione sopra oppure una delle seguenti dimensioni valide:

Generazione in batch

Seedream 4.5 include una modalità di generazione in batch che può essere usata per creare un set di immagini tematicamente correlate. Può essere utile, ad esempio, per generare uno storyboard o visual centrati su un soggetto comune.

Per generare un batch di immagini, dobbiamo fornire i parametri sequential_image_generation e sequential_image_generation_options nella richiesta API. Ecco un esempio per generare 4 immagini:

from byteplussdkarkruntime.types.images.images import SequentialImageGenerationOptions
prompt = """
Generate a series of four visually coherent and stylistically consistent images illustrating these stages of a human life: Child, Adolescent, Adult, and Elderly. Make sure it's the same person in the four images.
"""
imagesResponse = client.images.generate( 
    model="seedream-4-5-251128", 
    prompt=prompt,
    size="2K",
    sequential_image_generation="auto",
    sequential_image_generation_options=SequentialImageGenerationOptions(max_images=4),
    response_format="url",
    watermark=False
)

Quando usiamo la generazione in batch, otteniamo un formato di risposta diverso che contiene tutte le immagini. Possiamo iterare su quelle immagini e scaricarle così:

# Iterate through all image data
for image in imagesResponse.data:
    utils.download_image(image.url)

L'ho provato con il seguente prompt:

Generate a series of four visually coherent and stylistically consistent images illustrating these stages of a human life: Child, Adolescent, Adult, and Elderly. Make sure it's the same person in the four images.

Tuttavia, per qualche motivo, la quarta immagine rompeva sempre la coerenza e usciva come una donna (ho provato più volte).

Per generare un numero diverso di immagini, basta cambiare il valore max_images nella richiesta API. Questo numero può essere un intero tra 1 e 15 (inclusi). Ad esempio, per generare 6 immagini, faremmo così:

imagesResponse = client.images.generate( 
    model="seedream-4-5-251128", 
    prompt=prompt,
    size="2K",
    sequential_image_generation="auto",
    sequential_image_generation_options=SequentialImageGenerationOptions(max_images=6),
    response_format="url",
    watermark=False
)

Generazione di testo

Mettiamo alla prova la capacità di Seedream 4.5 di generare testo. Durante i test, ho voluto verificare se fosse in grado di generare un'immagine con una dimostrazione matematica senza specificare esplicitamente il testo da rendere. Questo mette alla prova anche la capacità del modello di comprendere il contesto.

Questo è il prompt che ho usato:

Generate an image of a math professor standing in front of a blackboard. On the blackboard, there is a written proof that the square root of 2 is irrational.

Ecco il risultato:

Sono rimasto piuttosto soddisfatto del risultato. Non solo la dimostrazione era corretta, ma il modello è stato in grado di gestire correttamente una grande quantità di testo.

Modificare immagini con Seedream 4.5

In questa sezione impariamo a modificare le immagini. Il modo più semplice per modificare un'immagine con Seedream 4.5 è fornire l'URL dell'immagine tramite il parametro image e descrivere le modifiche nel prompt.

Ecco un esempio di script completo:

from dotenv import load_dotenv
from byteplussdkarkruntime import Ark 
import os
import utils
load_dotenv()
client = Ark(
    base_url="https://ark.ap-southeast.bytepluses.com/api/v3", 
    api_key=os.getenv('ARK_API_KEY'), 
)
image = "https://images.pexels.com/photos/34408249/pexels-photo-34408249.jpeg"
prompt = """
Make in snowy.
"""
imagesResponse = client.images.generate( 
    model="seedream-4-5-251128", 
    prompt=prompt,
    image=image,
    response_format="url",
    watermark=False,
    size="1664x2496"
) 
 
image_url = imagesResponse.data[0].url
utils.download_image(image_url)

In questo esempio, ho usato una foto disponibile pubblicamente su Pexels di Michael Fischer e ho usato Seedream 4.5 per renderla innevata.

Questo è il risultato:

Nota che nell'esempio sopra abbiamo specificato esplicitamente la dimensione in output, "1664x2496", per mantenere il rapporto d'aspetto dell'immagine di input. A differenza della maggior parte dei modelli di immagini IA, Seedream 4.5 non genera automaticamente un'immagine con le stesse dimensioni dell'input. Quando ho omesso il parametro size, l'output era un'immagine quadrata.

Modificare immagini locali

Usare l'URL di un'immagine è il modo più semplice per fornirla a Seedream 4.5. Tuttavia, è scomodo se l'immagine non è già ospitata da qualche parte.

L'API Seedream ci consente anche di usare facilmente un'immagine locale. Per farlo, dobbiamo caricarla come immagine base64. Ecco una funzione per farlo:

import mimetypes
import base64
def load_image_as_base64(file_path):
    mime_type, _ = mimetypes.guess_type(file_path)
if mime_type is None or not mime_type.startswith("image/"):
        raise ValueError("File is not a recognized image type")
with open(file_path, "rb") as f:
        encoded = base64.b64encode(f.read()).decode("utf-8")
return f"data:{mime_type};base64,{encoded}"

Consiglio di aggiungerla al file utils.py che contiene la funzione per scaricare un'immagine, così sarà facile usarla nel nostro script principale.

Supponiamo di avere un'immagine locale nella stessa cartella chiamata motard.jpeg. Ecco come possiamo caricarla e modificarla:

image = utils.load_image_as_base64("motard.jpeg")
prompt = """
Remove the sunglasses and add a helmet.
"""
imagesResponse = client.images.generate( 
    model="seedream-4-5-251128", 
    prompt=prompt,
    image=image,
    response_format="url",
    watermark=False
) 

Editing con input multi-immagine

Seedream 4.5 supporta input con più immagini. Possono essere usati per generare una nuova immagine fondendo stili ed elementi visivi provenienti da quelle immagini.

Fornire più immagini in una richiesta API è semplice quanto passare un elenco di immagini. Ecco un esempio che combina l'immagine di una persona e un outfit in un'immagine di quella persona che indossa l'outfit:

image1 = utils.load_image_as_base64("woman.jpeg")
image2 = utils.load_image_as_base64("outfit.jpeg")
prompt = """
Make the woman from image 1 wear the outfit in image 2.
"""
imagesResponse = client.images.generate( 
    model="seedream-4-5-251128", 
    prompt=prompt,
    image=[image1, image2],
    response_format="url",
    watermark=False,
)

Questo esempio mostra che Seedream 4.5 è piuttosto bravo a preservare i volti; la persona nell'immagine finale somiglia ancora molto all'originale. È un aspetto in cui altri modelli tendono a rendere meno.

Editing con output multi-immagine

La funzionalità di batching vista sopra funziona anche per l'editing, dove il numero totale di immagini (input + output) non può superare 15. È molto utile, per esempio, per generare più immagini a partire da un visual.

Per farlo, basta combinare il parametro image con i parametri di generazione in batch visti sopra. Ecco un esempio di richiesta:

prompt = """
Use the given logo to create a visual design system for an outdoor hiking brand, 
including backpack, hat, and shoes.
"""
image = utils.load_image_as_base64("logo.jpeg")
imagesResponse = client.images.generate( 
    model="seedream-4-5-251128", 
    prompt=prompt,
    size="2K",
    image=image,
    sequential_image_generation="auto",
    sequential_image_generation_options=SequentialImageGenerationOptions(max_images=3),
    response_format="url",
    watermark=False
) 

Mascheratura

Alcuni modelli di generazione di immagini IA supportano la mascheratura consentendo agli utenti di fornire una maschera in bianco e nero per specificare le aree dell'immagine da modificare. Tuttavia, Seedream 4.5 non supporta nativamente i parametri di mascheratura.

Ci ho provato comunque inviando la maschera come immagine di input e specificando nel prompt cosa volevo, per vedere se il modello potesse comprendere ed emulare il risultato:

In questo esempio ha funzionato, ma poiché non è una funzionalità integrata nel modello, non è molto affidabile. Per esempio, quando ho provato ad aggiungere un cane, non ha funzionato.

Best practice per Seedream 4.5

Come abbiamo visto, Seedream 4.5 offre buone prestazioni e alcune funzioni interessanti. Per sfruttarlo al meglio, tieni a mente le seguenti best practice.

Linee guida fondamentali per i prompt

Per ottenere i migliori risultati di generazione da Seedream 4.5, rispondi alle domande cosa vuoi, perché lo vuoi e in che stile, mantenendo il tutto breve:

• Descrivi soggetto, azione e ambiente in linguaggio semplice.
• Specifica lo scopo/caso d'uso (logo, poster, storyboard, UI, ecc.).
• Controlla lo stile usando keyword precise o un'immagine di riferimento.
• Preferisci prompt concisi e precisi a lunghe liste di aggettivi.
• Metti tra virgolette doppie il testo che deve comparire nell'immagine.

Linee guida per l'editing di immagini

Quando modifichi immagini, indica esattamente quali cambiamenti fai e cosa deve restare invariato. Usa le seguenti quattro parole per specificare le azioni:

• Aggiungi
• Rimuovi
• Sostituisci
• Modifica

Se la scena è complessa, usare indizi visivi (frecce, riquadri, scarabocchi) per segnare le aree può aiutare il modello.

Quando usi un'immagine di riferimento per preservare identità, stile o caratteristiche di prodotto, specifica sempre:

• Target di riferimento: cosa estrarre/mantenere (ad es. design del personaggio, materiale, stile).
• Scena generata: dove/come usarlo (layout, ambientazione, realismo, dimensione, posizione).

Linee guida per il batching

Quando usi più immagini di input, assegna chiaramente i ruoli: 

• Quale fornisce il soggetto, quale fornisce outfit/stile/sfondo?
• Fai riferimento alle immagini come immagine 1, immagine 2, ecc.

Nonostante il modello abbia parametri per specificare quante immagini generare, è meglio assicurarsi di indicare anche nel prompt ciò che vogliamo:

• Chiedi "una serie", "un set" o specifica il numero esatto di immagini.
• Usalo per storyboard, fumetti, set di brand coerenti, pacchetti di emoji, ecc.

Conclusione

Seedream 4.5 appare come un generatore di immagini maturo e pronto per la produzione, all'altezza di modelli di fascia alta come Nano Banana, con una fedeltà comparabile, aderenza alle istruzioni e coerenza tra immagini, restando al contempo conveniente.

Ciò che mi ha colpito è quanto l'API risulti accessibile nella pratica: lo stesso endpoint di generazione gestisce la creazione singola, gli edit (via URL o base64), i blend multi-immagine e i batch sequenziali, e abilitiamo ciascuna modalità agendo su un piccolo set di parametri chiaramente denominati.

Detto questo, non mi sembra che porti particolari innovazioni: è un'ottima, ben eseguita interpretazione della ormai familiare cassetta degli attrezzi per la generazione di immagini più che un salto concettuale.

Per approfondire

Se vuoi mantenere lo slancio dopo questa guida, considera di rafforzare le basi che rendono fluidi i progetti con Seedream 4.5 in produzione.

Inizia con il corso Introduction to APIs in Python per padroneggiare richieste autenticate e gestione degli errori, abbinalo a Image Processing in Python per gestire ridimensionamento, compositing e conversioni di formato nelle tue pipeline.

Se punti a un percorso più formale verso il ML applicato e gli strumenti, il career track AI Engineer riunisce il tutto con workflow per distribuire funzionalità di IA affidabili e scalabili.