Istruzioni di integrazione dell'API SeeDream Images Generation

Questo articolo presenterà una guida all’integrazione dell’API SeeDream Images Generation, che consente di generare immagini ufficiali di SeeDream inserendo parametri personalizzati.

Procedura di richiesta

Per utilizzare l’API SeeDream Images Generation, vai prima alla console di Ace Data Cloud per ottenere il tuo API Token, da conservare come riserva.

Se non hai ancora effettuato l’accesso o la registrazione, verrai automaticamente reindirizzato alla pagina di accesso che ti inviterà a registrarti e ad accedere; al termine, tornerai automaticamente alla pagina corrente. Un solo API Token può chiamare tutti i servizi della piattaforma, senza doverne richiedere uno separatamente per ogni servizio. Alla prima richiesta verrà assegnato un credito gratuito, utilizzabile per una prova gratuita; quando il credito è insufficiente, puoi ricaricare il saldo universale nella console.

📘 Documentazione completa: SeeDream Images Generation API →

Utilizzo di base

Comprendiamo prima il metodo di utilizzo di base: inserendo il prompt prompt, l’azione di generazione action e la dimensione dell’immagine size, è possibile ottenere il risultato elaborato. Per prima cosa è necessario passare semplicemente un campo action, il cui valore è generate, quindi dobbiamo anche inserire il prompt; il contenuto specifico è il seguente:

Qui possiamo vedere che abbiamo impostato i Request Headers, inclusi:

accept: il formato del risultato di risposta che si desidera ricevere; qui viene compilato come application/json, ovvero il formato JSON.
authorization: la chiave per chiamare l’API, che può essere selezionata direttamente dal menu a discesa dopo la richiesta.

Inoltre, è stato impostato il Request Body, incluso:

prompt: prompt.
model: modello di generazione, predefinito doubao-seedream-5-0-lite-260128 (SeeDream 5.0 Lite, il più recente). Supporta doubao-seedream-5-0-pro-260628, 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 punta per immagini singole, genera soltanto immagini singole e non supporta gruppi di immagini (sequential_image_generation), streaming (stream) e ricerca web (tools). model deve ricevere la stringa completa del modello (ad esempio doubao-seedream-5-0-lite-260128); passando abbreviazioni come doubao-seedream-5.0-lite verrà restituito 400.
image: informazioni sull’immagine di input, supporta URL o codifica Base64. doubao-seedream-5-0-pro-260628 supporta l’input di una o più immagini (massimo 10), mentre doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 supportano l’input di una o più immagini.
size: specifica le informazioni sulla dimensione dell’immagine generata; supporta i seguenti due metodi, che non possono essere combinati. Metodo 1 | Specifica la risoluzione dell’immagine generata e descrivi il rapporto larghezza-altezza dell’immagine in linguaggio naturale nel prompt. Le preimpostazioni supportate variano per ciascun modello: doubao-seedream-5-0-pro-260628 supporta 1K/1.5K/2K; doubao-seedream-5-0-lite-260128 supporta 2K/3K/4K; doubao-seedream-4-5-251128 supporta soltanto 2K/4K; doubao-seedream-4-0-250828 supporta 1K/2K/4K. Metodo 2 | Specifica i valori in pixel di larghezza e altezza dell’immagine generata: il valore predefinito è 2048x2048; l’intervallo dei pixel totali e del rapporto larghezza-altezza varia in base al modello (ad esempio, per 5.0 Pro l’intervallo dei pixel totali è [921600, 4624220], il limite inferiore dei pixel totali per 5.0 Lite / 4.5 è 3,686,400, e per 4.0 il limite inferiore è 921,600).
sequential_image_generation: gruppo di immagini: un gruppo di immagini con contenuti correlati generato in base al contenuto inserito. doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 supportano questo parametro, il cui valore predefinito è disabled.
stream: controlla se abilitare la modalità di output in streaming. doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 supportano questo parametro, il cui valore predefinito è false.
response_format: specifica il formato di ritorno dell’immagine generata. Il valore predefinito è url, ed è supportato anche b64_json.
watermark: se aggiungere una filigrana all’immagine generata. Il valore predefinito è true.
output_format: specifica il formato del file dell’immagine generata, supporta jpeg (predefinito) e png. Supportato soltanto da doubao-seedream-5-0-pro-260628 e doubao-seedream-5-0-lite-260128.
tools: configura gli strumenti che il modello deve chiamare; attualmente supporta web_search (ricerca web). Supportato soltanto da Seedream 5.0 Lite.
optimize_prompt_options: configurazione dell’ottimizzazione del prompt. 5.0 Pro supporta standard/fast; 5.0 Lite e 4.5 supportano soltanto standard; 4.0 supporta standard/fast.
background: supportato soltanto dalla modifica di immagini singole di 5.0 Pro. transparent richiede l’input di una PNG con canale trasparente e output_format deve essere png; opaque indica un normale sfondo opaco.
layer_decomposition: supportato soltanto da 5.0 Pro. Quando impostato su true, è necessario inserire una PNG/JPEG; è possibile non passare prompt per la suddivisione automatica oppure specificare elementi con linguaggio naturale/<bbox>; size supporta auto/1K/1.5K/2K. Questa modalità non può essere utilizzata insieme a gruppi di immagini, streaming, ricerca web o background.
callback_url: URL che necessita del risultato di callback.
async: se elaborare in modalità asincrona. Quando impostato su true, l’interfaccia restituisce immediatamente task_id, senza necessità di fornire callback_url; successivamente, utilizza /seedream/tasks per interrogare il risultato.

Dopo la selezione, puoi notare che viene generato anche il codice corrispondente sul lato destro, come mostrato nell’immagine:

Fai clic sul pulsante «Try» per eseguire il test; come mostrato nell’immagine sopra, qui abbiamo ottenuto il seguente risultato:

{
  "success": true,
  "task_id": "80ceeed1-17d4-4eb7-82e0-18b34290f36e",
  "trace_id": "96b7fdc8-0fc8-4e2e-82a9-83c0a82f0a08",
  "data": [
    {
      "prompt": "A single matte blue cube centered on a clean white studio background, neutral lighting",
      "size": "2048x2048",
      "image_url": "https://cdn.acedata.cloud/assets/examples/seedream/db93b46e-c302-4676-8a11-63f0ba638a27-1c6f66f6b7e8.jpg"
    }
  ]
}

Il risultato restituito contiene più campi, descritti come segue:

success, lo stato dell’attuale attività di generazione video.
task_id, l’ID dell’attuale attività di generazione video.
trace_id, l’ID di tracciamento dell’attuale generazione video.
data, l’elenco dei risultati dell’attuale attività di generazione immagini.
- image_url, il link dell’attuale attività di generazione immagini.
- prompt, il prompt.
- size: i pixel dell’immagine generata

Si può vedere che abbiamo ottenuto informazioni soddisfacenti sull’immagine, dobbiamo solo ottenere l’immagine SeeDream generata in base all’indirizzo del link dell’immagine in data nel risultato. Inoltre, se si desidera generare il codice di integrazione corrispondente, è possibile copiarlo direttamente per generarlo, 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-lite-260128",
  "prompt": "A single matte blue cube centered on a clean white studio background, neutral lighting"
}'

Attività di modifica immagini

Se si desidera modificare una determinata immagine, innanzitutto il parametro image deve trasmettere il link dell’immagine da modificare

model: il modello adottato da questa attività di modifica immagini, doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 supportano tutti l’input di immagini.
image: caricare l’immagine da modificare, una o più immagini

L’esempio di compilazione è il seguente:

Il 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": "Keep the model pose and the liquid garment flowing shape unchanged. Change the clothing material from silver metal to completely transparent water (or glass). Through the liquid flow, the details of the model skin are visible. The light and shadow effect shifts from reflection to refraction.",
  "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)

Fare clic su Esegui, si può notare che si ottiene immediatamente un risultato, come segue:

{
  "success": true,
  "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
  "trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
  "data": [
    {
      "prompt": "Keep the model pose and the liquid garment flowing shape unchanged. Change the clothing material from silver metal to completely transparent water (or glass). Through the liquid flow, the details of the model skin are visible. The light and shadow effect shifts from reflection to refraction.",
      "size": "2048x2048",
      "image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
    }
  ]
}

Si può vedere che l’effetto generato è l’effetto di modifica dell’immagine originale, il risultato è simile a quello sopra.

Scomposizione dei livelli (Seedream 5.0 Pro)

La scomposizione dei livelli divide un’immagine di input in 1 immagine di sfondo e fino a 16 livelli PNG trasparenti modificabili in modo indipendente. La seguente richiesta consente al modello di riconoscere automaticamente gli elementi principali; se è necessario specificare elementi, è possibile aggiungere prompt, ed è anche possibile utilizzare coordinate <bbox> normalizzate nel prompt.

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 data restituiti sono ordinati dal basso verso l’alto in base a z_index. Il z_index dell’immagine di sfondo è 0; i livelli includono anche name, description e bounding_box.absolute/normalized. Quando si ricompone utilizzando coordinate assolute, ridimensionare il livello a [right-left, bottom-top], posizionarlo in [left, top], quindi sovrapporlo in ordine crescente di z_index. Se la generazione di un qualsiasi livello fallisce, l’intera scomposizione 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 l’unico evento image_generation.completed e l’usage finale; solo l’evento di completamento attiva una fatturazione. La modalità streaming non può essere usata insieme ad async o callback_url.

Callback asincrono

Poiché il tempo di generazione della SeeDream Images Generation API è relativamente lungo, richiede circa 1-2 minuti, se l’API non risponde per molto tempo, la richiesta HTTP manterrà sempre la connessione, causando un consumo aggiuntivo di risorse di sistema, quindi questa API fornisce anche il supporto per callback asincroni. Il processo complessivo è: quando il client avvia una richiesta, specifica inoltre un campo callback_url, dopo che il client ha avviato la richiesta API, l’API restituirà immediatamente un risultato, contenente le informazioni di un campo task_id, che rappresenta l’ID dell’attività corrente. Dopo il completamento dell’attività, il risultato dell’immagine generata verrà inviato tramite POST JSON al callback_url specificato dal client, includendo anch’esso il campo task_id, in questo modo il risultato dell’attività può essere associato tramite l’ID. Se non si dispone di un indirizzo pubblico per il callback, è anche possibile non specificare callback_url, ma impostare il campo async su true nella richiesta. In questo caso l’interfaccia restituirà ugualmente immediatamente task_id, ma non invierà il risultato, sarà necessario utilizzare questo task_id per chiamare l’interfaccia /seedream/tasks e interrogare ciclicamente lo stato dell’attività per ottenere il risultato finale. Di seguito comprendiamo tramite un esempio come operare concretamente. Fare clic su Esegui, si può notare che si ottiene immediatamente un risultato, come segue:

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

Il contenuto è il seguente:

{
    "success": true,
    "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
    "trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
    "data": [
        {
            "prompt": "Keep the model pose and the liquid garment flowing shape unchanged. Change the clothing material from silver metal to completely transparent water (or glass). Through the liquid flow, the details of the model skin are visible. The light and shadow effect shifts from reflection to refraction.",
            "size": "2048x2048",
            "image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
        }
    ]
}

Si può vedere che nel risultato è presente un campo task_id; gli altri campi sono simili a quelli sopra indicati e l’associazione dell’attività può essere realizzata tramite questo campo.

Gestione degli errori

Quando si chiama l’API, se si verifica un errore, l’API restituirà il codice e le informazioni di errore 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 già compreso come utilizzare la SeeDream Images Generation API per generare immagini inserendo prompt. Ci auguriamo che questo documento possa aiutarti a integrare e utilizzare meglio questa API. In caso di 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à

Coding

Altre guide

Istruzioni di integrazione dell'API SeeDream Images Generation

Procedura di richiesta

Utilizzo di base

Attività di modifica immagini

Scomposizione dei livelli (Seedream 5.0 Pro)

Output in streaming

Callback asincrono

Gestione degli errori

Esempio di risposta di errore

Conclusione

​Procedura di richiesta

​Utilizzo di base

​Attività di modifica immagini

​Scomposizione dei livelli (Seedream 5.0 Pro)

​Output in streaming

​Callback asincrono

​Gestione degli errori

​Esempio di risposta di errore

​Conclusione

Procedura di richiesta

Utilizzo di base

Attività di modifica immagini

Scomposizione dei livelli (Seedream 5.0 Pro)

Output in streaming

Callback asincrono

Gestione degli errori

Esempio di risposta di errore

Conclusione