Skip to main content
Questo documento introduce una guida all’integrazione dell’API SeeDream Images Generation, che consente di generare immagini ufficiali di SeeDream tramite l’inserimento di parametri personalizzati.

​
Processo di richiesta

Per utilizzare l’API SeeDream Images Generation, prima di tutto vai al Pannello di controllo di Ace Data Cloud per ottenere il tuo API Token, da conservare per uso futuro. Se non hai ancora effettuato il login o la registrazione, verrai automaticamente reindirizzato alla pagina di login che ti invita a registrarti e accedere; una volta completato, verrai riportato automaticamente alla pagina corrente. Un API Token è sufficiente per accedere a tutti i servizi della piattaforma, senza necessità di richiederne uno per ogni servizio. La prima richiesta offre un credito gratuito, per un’esperienza senza costi; quando il credito è insufficiente, puoi ricaricare il saldo generale nel pannello di controllo.
📘 Documentazione completa: SeeDream Images Generation API →

​
Utilizzo di base

Iniziamo a comprendere il modo di utilizzo di base, che consiste nell’inserire la parola chiave prompt, l’azione action, e le dimensioni dell’immagine size, per ottenere il risultato elaborato. Prima di tutto, è necessario passare un campo action, il cui valore è generate, e poi dobbiamo inserire la parola chiave, i dettagli sono i seguenti:

Possiamo vedere che qui abbiamo impostato le intestazioni della richiesta, che includono:
  • accept: il formato della risposta desiderata, qui impostato su application/json, ovvero formato JSON.
  • authorization: la chiave per chiamare l’API, che può essere selezionata direttamente dopo la richiesta.
Inoltre, abbiamo impostato il corpo della richiesta, che include:
  • prompt: parola chiave.
  • model: modello di generazione, predefinito doubao-seedream-5-0-260128 (SeeDream 5.0 Lite, l’ultimo). Supporta doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828, doubao-seedream-3-0-t2i-250415, doubao-seededit-3-0-i2i-250628. Tra questi, doubao-seedream-5-0-pro-260628 (SeeDream 5.0 Pro) è il modello di immagine singola di punta, genera solo immagini singole, non supporta la generazione di immagini multiple (sequential_image_generation), streaming (stream) e ricerca online (tools). model deve essere passato come stringa completa del modello (ad esempio doubao-seedream-5-0-260128), passare abbreviazioni come doubao-seedream-5.0-lite restituirà un errore 400.
  • image: informazioni sull’immagine di input, supporta URL o codifica Base64. Tra questi, doubao-seedream-5-0-pro-260628 supporta input di immagini singole o multiple (da 2 a 10 immagini, dalla seconda in poi si paga per immagine), doubao-seedream-5-0-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 supportano input di immagini singole o multiple, doubao-seededit-3-0-i2i-250628 supporta solo input di immagini singole, doubao-seedream-3-0-t2i-250415 non supporta questo parametro.
  • size: specifica le informazioni sulle dimensioni dell’immagine generata, supporta i seguenti due metodi, non utilizzabili insieme. Metodo 1 | Specifica la risoluzione dell’immagine generata e descrive il rapporto di aspetto dell’immagine in linguaggio naturale nel prompt. Le impostazioni predefinite supportate variano a seconda del modello: doubao-seedream-5-0-pro-260628 supporta 1K/2K; doubao-seedream-5-0-260128 supporta 2K/3K/4K; doubao-seedream-4-5-251128 supporta solo 2K/4K; doubao-seedream-4-0-250828 supporta 1K/2K/4K; doubao-seedream-3-0-t2i-250415 e doubao-seededit-3-0-i2i-250628 non supportano le impostazioni predefinite, accettano solo il metodo 2. Metodo 2 | Specifica i valori di pixel per larghezza e altezza dell’immagine generata: predefinito 2048x2048, il range totale di pixel e il rapporto di aspetto variano a seconda del modello (ad esempio, il range totale di pixel per 5.0 Pro è [921600, 4194304], per 5.0 Lite / 4.5 il limite inferiore totale di pixel è 3.686.400, per 4.0 il limite inferiore è 921.600, per 3.0-t2i / seededit-3.0-i2i il range è [512x512, 2048x2048]).
  • seed: seme casuale, utilizzato per controllare la casualità del contenuto generato dal modello. Il range di valori è [-1, 2147483647]. Solo doubao-seedream-3-0-t2i-250415 supporta questo parametro.
  • sequential_image_generation: immagini multiple: genera un insieme di immagini correlate basate sul contenuto che hai inserito. doubao-seedream-5-0-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 supportano questo parametro, predefinito disabilitato.
  • stream: controlla se attivare la modalità di output in streaming. doubao-seedream-5-0-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 supportano questo parametro, predefinito è false.
  • guidance_scale: grado di coerenza tra il risultato del modello e il prompt, maggiore è il valore, più forte è la correlazione. Range di valori [1, 10]. doubao-seedream-3-0-t2i-250415 valore predefinito 2.5, doubao-seededit-3-0-i2i-250628 valore predefinito 5.5, altri modelli non supportano.
  • response_format: specifica il formato di ritorno dell’immagine generata. Predefinito è url, supporta anche b64_json.
  • watermark: se aggiungere un watermark all’immagine generata. Predefinito è true.
  • output_format: specifica il formato del file dell’immagine generata, supporta jpeg (predefinito) e png. Solo doubao-seedream-5-0-pro-260628 e doubao-seedream-5-0-260128 supportano.
  • tools: configura gli strumenti che il modello deve chiamare, attualmente supporta web_search (ricerca online). Solo doubao-seedream-5-0-260128 supporta.
  • callback_url: URL per il quale è necessario il risultato del callback.
  • async: se elaborare in modalità asincrona. Impostato su true, l’interfaccia restituisce immediatamente task_id, senza necessità di fornire callback_url, successivamente puoi ottenere i risultati tramite /seedream/tasks.
Dopo aver effettuato la selezione, puoi notare che a destra è stato generato anche il codice corrispondente, come mostrato nell’immagine:

Cliccando sul pulsante “Prova” puoi effettuare un test, come mostrato nell’immagine sopra, qui abbiamo ottenuto il seguente risultato:
I risultati restituiti contengono diversi campi, come segue:
  • success, lo stato attuale del compito di generazione video.
  • task_id, l’ID del compito di generazione video attuale.
  • trace_id, l’ID di tracciamento del compito di generazione video attuale.
  • data, l’elenco dei risultati del compito di generazione immagine attuale.
    • image_url, il link al compito di generazione immagine attuale.
    • prompt, la parola chiave.
    • size: i pixel dell’immagine generata.
Possiamo vedere che abbiamo ottenuto informazioni sull’immagine soddisfacenti, dobbiamo solo ottenere l’immagine generata di SeeDream dal link dell’immagine nel risultato data. Inoltre, se desideri generare il codice corrispondente, puoi semplicemente copiare e generare, ad esempio, il codice CURL è il seguente:

​
Modifica del compito di immagine

Se desideri modificare un’immagine, prima il parametro image deve contenere il link dell’immagine da modificare.
  • model: il modello utilizzato per il compito di modifica dell’immagine, doubao-seedream-5-0-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 supportano input singolo o multiplo, doubao-seededit-3-0-i2i-250628 supporta solo input singolo.
  • image: carica l’immagine da modificare, una o più.
Esempio di compilazione:

Codice corrispondente:
Cliccando su Esegui, puoi vedere che otterrai immediatamente un risultato, come segue:
Possiamo vedere che l’effetto generato è il risultato della modifica dell’immagine originale, simile al risultato sopra.

​
Callback asincrona

Poiché l’API di generazione immagini SeeDream richiede un tempo relativamente lungo, circa 1-2 minuti, se l’API non risponde per lungo tempo, la richiesta HTTP manterrà la connessione, causando un consumo aggiuntivo di risorse di sistema, quindi questa API offre anche supporto per callback asincroni. Il flusso generale è: quando il client invia la richiesta, specifica un campo callback_url aggiuntivo, dopo che il client ha inviato la richiesta API, l’API restituirà immediatamente un risultato, contenente un campo task_id, che rappresenta l’ID del compito attuale. Quando il compito è completato, il risultato dell’immagine generata verrà inviato al callback_url specificato dal client in formato JSON POST, che include anche il campo task_id, in modo che il risultato del compito possa essere associato tramite l’ID. Se non hai un indirizzo pubblico disponibile per il callback, puoi anche non specificare callback_url, ma impostare il campo async nella richiesta su true. In questo caso, l’interfaccia restituirà immediatamente task_id, ma non invierà il risultato, dovrai portare quel task_id per chiamare l’interfaccia /seedream/tasks per interrogare lo stato del compito e ottenere il risultato finale. Di seguito, attraverso un esempio, vediamo come operare concretamente. Cliccando su Esegui, puoi vedere che otterrai immediatamente un risultato, come segue:
Il contenuto è il seguente:
Possiamo vedere che nel risultato c’è un campo task_id, gli altri campi sono simili a quelli sopra, tramite questo campo è possibile realizzare l’associazione del compito.

​
Gestione degli errori

Quando si chiama l’API, se si verifica un errore, l’API restituirà il codice di errore e le informazioni corrispondenti. Ad esempio:
  • 400 token_mismatched: Richiesta non valida, probabilmente a causa di parametri mancanti o non validi.
  • 400 api_not_implemented: Richiesta non valida, probabilmente a causa di parametri mancanti o non validi.
  • 401 invalid_token: Non autorizzato, token di autorizzazione non valido o mancante.
  • 429 too_many_requests: Troppe richieste, hai superato il limite di frequenza.
  • 500 api_error: Errore interno del server, qualcosa è andato storto sul server.

​
Esempio di risposta di errore

​
Conclusione

Attraverso questo documento, hai già compreso come utilizzare l’API di generazione immagini SeeDream per generare immagini inserendo parole chiave. Speriamo che questo documento possa aiutarti a integrare e utilizzare meglio questa API. Se hai domande, non esitare a contattare il nostro team di supporto tecnico.