> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# SeeDream Images Generation API integrazione
> ByteDance Seedream Image Generation API guide - Ace Data Cloud
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](https://platform.acedata.cloud/console/applications) 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](https://platform.acedata.cloud/console/coin).
> 📘 Documentazione completa: [SeeDream Images Generation API →](https://platform.acedata.cloud/documents/seedream-images)
## 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:
```json theme={null}
{
"success": true,
"task_id": "81246f86-05ff-4d7d-9553-1013e0c1cd32",
"trace_id": "ab50a78d-ab1f-457f-a46b-c2259cd5d35b",
"data": [
{
"prompt": "Una foto di prodotto fotorealistica 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:
```shell theme={null}
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 di prodotto fotorealistica 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."
}'
```
## 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:
```python theme={null}
import requests
url = "https://api.acedata.cloud/flux/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:
```json theme={null}
{
"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.
## 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:
```
{
"task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde"
}
```
Il contenuto è il seguente:
```json theme={null}
{
"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 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
```json theme={null}
{
"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 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.