SeeDream Images Generation API Integrazione Istruzioni

Questo documento presenterà un’istruzione per l’integrazione dell’API SeeDream Images Generation, che consente di generare immagini ufficiali di SeeDream inserendo 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 ti darà 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 →

Uso di Base

Per prima cosa, è importante 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. È necessario prima 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 (accetta anche il nome alternativo ufficiale doubao-seedream-5-0-lite-260128), doubao-seedream-4-5-251128, doubao-seedream-4-0-250828. Tra questi, doubao-seedream-5-0-pro-260628 (SeeDream 5.0 Pro) è il modello di immagine singola di punta, genera solo un’immagine singola, non supporta la generazione di immagini sequenziali (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à 400.
image: informazioni sull’immagine di input, supporta URL o codifica Base64. 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.
size: specifica le dimensioni dell’immagine generata, supporta i seguenti due metodi, non possono essere mescolati. 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 tra i modelli: doubao-seedream-5-0-pro-260628 supporta 1K/1.5K/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. Metodo 2 | Specifica i valori dei pixel di larghezza e altezza dell’immagine generata: predefinito 2048x2048, il totale dei pixel e il rapporto di aspetto variano a seconda del modello (ad esempio, il totale dei pixel per 5.0 Pro varia da [921600, 4624220], il limite inferiore per 5.0 Lite / 4.5 è 3.686.400, per 4.0 è 921.600).
sequential_image_generation: immagini di gruppo: 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.
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 Seedream 5.0 Lite supporta.
optimize_prompt_options: configurazione per l’ottimizzazione della parola chiave. 5.0 Pro supporta standard/fast; 5.0 Lite e 4.5 supportano solo standard; 4.0 supporta standard/fast.
background: supportato solo per l’editing di immagini singole 5.0 Pro. transparent richiede l’input di un PNG con canale trasparente, e output_format deve essere png; opaque è uno sfondo normale opaco.
layer_decomposition: supportato solo per 5.0 Pro. Se impostato su true, è necessario fornire un PNG/JPEG, non è necessario passare prompt per la suddivisione automatica, o specificare elementi in linguaggio naturale/<bbox>; size supporta auto/1K/1.5K/2K. Questa modalità non può essere utilizzata con immagini di gruppo, streaming, ricerca online o background.
callback_url: URL per il quale è necessario il risultato del callback.
async: se elaborare in modalità asincrona. Se 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 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:

{
  "success": true,
  "task_id": "81246f86-05ff-4d7d-9553-1013e0c1cd32",
  "trace_id": "ab50a78d-ab1f-457f-a46b-c2259cd5d35b",
  "data": [
    {
      "prompt": "Una foto realistica di un prodotto in studio di una bottiglia di profumo in vetro smerigliato su ardesia nera bagnata, luce principale softbox singola, gocce d'acqua, sfondo scuro e moody, 85mm macro.",
      "size": "2048x2048",
      "image_url": "https://platform2.cdn.acedata.cloud/seedream/901c6af6-e83a-4849-b233-295f6c20bacb.jpg"
    }
  ]
}

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:

curl -X POST 'https://api.acedata.cloud/seedream/images' \
-H 'accept: application/json' \
-H 'authorization: Bearer ${token}' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "model": "doubao-seedream-5-0-260128",
  "prompt": "Una foto realistica di un prodotto in studio di una bottiglia di profumo in vetro smerigliato su ardesia nera bagnata, luce principale softbox singola, gocce d'acqua, sfondo scuro e moody, 85mm macro."
}'

Compito di modifica dell’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-pro-260628, doubao-seedream-5-0-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 supportano tutti l’input dell’immagine.
image: carica l’immagine da modificare, una o più.

Esempio di compilazione:

Codice corrispondente:

import requests

url = "https://api.acedata.cloud/seedream/images"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "doubao-seedream-4-0-250828",
  "prompt": "Mantieni la posa del modello e la forma fluente del capo liquido invariati. Cambia il materiale dell'abbigliamento da metallo argentato a acqua completamente trasparente (o vetro). Attraverso il flusso liquido, i dettagli della pelle del modello sono visibili. L'effetto di luce e ombra passa da riflessione a rifrazione.",
  "image": ["https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_5_imageToimage.png"],
  "size": "2K",
  "watermark": False
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Cliccando su Esegui, puoi vedere che otterrai immediatamente un risultato, come segue:

{
  "success": true,
  "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
  "trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
  "data": [
    {
      "prompt": "Mantieni la posa del modello e la forma fluente del capo liquido invariati. Cambia il materiale dell'abbigliamento da metallo argentato a acqua completamente trasparente (o vetro). Attraverso il flusso liquido, i dettagli della pelle del modello sono visibili. L'effetto di luce e ombra passa da riflessione a rifrazione.",
      "size": "2048x2048",
      "image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
    }
  ]
}

Possiamo vedere che l’effetto generato è il risultato della modifica dell’immagine originale, simile al risultato sopra.

Separazione dei livelli (Seedream 5.0 Pro)

La separazione dei livelli suddividerà un’immagine di input in 1 immagine di base e fino a 16 livelli PNG trasparenti modificabili in modo indipendente. La seguente richiesta consente al modello di riconoscere automaticamente gli elementi principali; se desideri specificare gli elementi, puoi aggiungere prompt, oppure puoi utilizzare le coordinate normalizzate <bbox> nelle parole chiave.

curl -X POST 'https://api.acedata.cloud/seedream/images' \
-H 'accept: application/json' \
-H 'authorization: Bearer ${token}' \
-H 'content-type: application/json' \
-d '{
  "model": "doubao-seedream-5-0-pro-260628",
  "image": "https://example.com/poster.png",
  "layer_decomposition": true,
  "size": "2K",
  "watermark": false
}'

I dati restituiti sono ordinati per z_index dal basso verso l’alto. L’immagine di base ha z_index pari a 0; i livelli includono anche name, description e bounding_box.absolute/normalized. Quando si ricompongono utilizzando coordinate assolute, i livelli vengono scalati a [right-left, bottom-top], posizionati a [left, top], e poi sovrapposti in ordine crescente di z_index. Se un livello fallisce nella generazione, l’intera separazione fallisce.

Output in streaming

Quando Lite/4.x imposta stream: true, l’intestazione della richiesta utilizza accept: application/x-ndjson. L’interfaccia restituisce riga per riga image_generation.partial_succeeded o image_generation.partial_failed, e infine restituisce un evento unico image_generation.completed e il usage finale; solo l’evento di completamento attiva una fatturazione. La modalità di streaming non può essere utilizzata insieme a async o callback_url.

Callback asincrona

Poiché il tempo di generazione dell’API SeeDream Images Generation è 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 complessivo è: quando il client avvia la richiesta, specifica un campo callback_url aggiuntivo, dopo che il client ha avviato 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 ID. Se non hai un indirizzo pubblico disponibile per il callback, puoi anche non specificare callback_url, ma impostare il campo async su true nella richiesta. 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:

{
  "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde"
}

Il contenuto è il seguente:

```json
{
    "success": true,
    "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
    "trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
    "data": [
        {
            "prompt": "Mantieni la posa del modello e la forma fluente del indumento liquido invariati. Cambia il materiale dell'abbigliamento da metallo argentato a acqua completamente trasparente (o vetro). Attraverso il flusso liquido, i dettagli della pelle del modello sono visibili. L'effetto di luce e ombra passa da riflessione a rifrazione.",
            "size": "2048x2048",
            "image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
        }
    ]
}

Si può vedere che nel risultato c’è un campo task_id, gli altri campi sono simili a quelli sopra, attraverso 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

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusione

Attraverso questo documento, hai compreso come utilizzare l’API di generazione immagini SeeDream per generare immagini tramite l’inserimento di 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.

Inizia

Chat AI

Immagine AI

Video AI

Audio AI

Web e Dati

CAPTCHA

Identità

Proxy

Avanzato

Coding

SeeDream Images Generation API Integrazione Istruzioni

Processo di Richiesta

Uso di Base

Compito di modifica dell’immagine

Separazione dei livelli (Seedream 5.0 Pro)

Output in streaming

Callback asincrona

Gestione degli errori

Esempio di risposta di errore

Conclusione

​Processo di Richiesta

​Uso di Base

​Compito di modifica dell’immagine

​Separazione dei livelli (Seedream 5.0 Pro)

​Output in streaming

​Callback asincrona

​Gestione degli errori

​Esempio di risposta di errore

​Conclusione

Processo di Richiesta

Uso di Base

Compito di modifica dell’immagine

Separazione dei livelli (Seedream 5.0 Pro)

Output in streaming

Callback asincrona

Gestione degli errori

Esempio di risposta di errore

Conclusione