> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Istruzioni per l'integrazione con SeeDream Images Generation API
> ByteDance Seedream Image Generation 集成指南 - XHuoAPI
Questo documento introduce le istruzioni per l'integrazione con SeeDream Images Generation API, che consente di generare immagini ufficiali SeeDream tramite l'inserimento di parametri personalizzati.
## Procedura di richiesta
Per utilizzare l'API, è necessario prima richiedere il servizio corrispondente sulla pagina [SeeDream Images Generation API](https://api.xhuoapi.ai/documents/seedream-images). Una volta entrati nella pagina, cliccare sul pulsante "Acquire", come mostrato nell'immagine:
Se non si è ancora effettuato l'accesso o la registrazione, si verrà automaticamente reindirizzati alla pagina di login per registrarsi e accedere; al termine si tornerà automaticamente alla pagina corrente.
Alla prima richiesta verrà offerto un credito gratuito per utilizzare l'API senza costi.
## Uso base
Per prima cosa, vediamo il modo base di utilizzo: inserire il prompt `prompt`, l'azione di generazione `action` e la dimensione dell'immagine `size` per ottenere il risultato elaborato. È necessario fornire un campo `action` con valore `generate` e inserire il prompt. Ecco un esempio:
Qui sono impostate le Request Headers, tra cui:
* `accept`: formato della risposta desiderata, qui impostato su `application/json` (formato JSON).
* `authorization`: chiave API per chiamare l'API, selezionabile dopo la richiesta.
Nel Request Body sono inclusi:
* `prompt`: il prompt.
* `model`: modello di generazione, predefinito `doubao-seedream-5.0-lite`. Supporta `doubao-seedream-5.0-lite` (ultimo), `doubao-seedream-4.5`, `doubao-seedream-4.0`, `doubao-seedream-3.0-t2i`, `doubao-seededit-3.0-i2i`.
* `image`: informazioni sull'immagine di input, supporta URL o codifica Base64. `doubao-seedream-5.0-lite`, `doubao-seedream-4.5`, `doubao-seedream-4.0` supportano input singolo o multiplo; `doubao-seededit-3.0-i2i` solo singolo; `doubao-seedream-3.0-t2i` non supporta questo parametro.
* `size`: specifica la dimensione dell'immagine generata, con due modalità non combinabili. Modalità 1 | specifica la risoluzione e descrive il rapporto d’aspetto in linguaggio naturale nel prompt. **Le preimpostazioni variano per modello**: `doubao-seedream-5.0-lite` supporta `2K`/`3K`/`4K`; `doubao-seedream-4.5` solo `2K`/`4K`; `doubao-seedream-4.0` supporta `1K`/`2K`/`4K`; `doubao-seedream-3.0-t2i` e `doubao-seededit-3.0-i2i` **non supportano preimpostazioni**, accettano solo modalità 2. Modalità 2 | specifica i pixel di larghezza e altezza: predefinito `2048x2048`, con limiti di pixel totali e rapporto d’aspetto variabili per modello (es. 5.0 / 4.5 limite inferiore 3.686.400 pixel, 4.0 limite 921.600, 3.0-t2i / seededit-3.0-i2i range \[512x512, 2048x2048]).
* `seed`: seme casuale per controllare la casualità della generazione. Range \[-1, 2147483647]. **Supportato solo da `doubao-seedream-3.0-t2i`**.
* `sequential_image_generation`: generazione di immagini correlate in gruppo basata sul contenuto inserito. Supportato da `doubao-seedream-5.0-lite`, `doubao-seedream-4.5`, `doubao-seedream-4.0`, default `disabled`.
* `stream`: abilita modalità di output in streaming. Supportato da `doubao-seedream-5.0-lite`, `doubao-seedream-4.5`, `doubao-seedream-4.0`, default `false`.
* `guidance_scale`: grado di coerenza tra output del modello e prompt, più alto significa maggiore correlazione. Range \[1, 10]. Default 2.5 per `doubao-seedream-3.0-t2i`, 5.5 per `doubao-seededit-3.0-i2i`, non supportato dagli altri modelli.
* `response_format`: formato di ritorno dell’immagine generata. Default `url`, supporta anche `b64_json`.
* `watermark`: se aggiungere watermark all’immagine generata. Default `true`.
* `output_format`: formato file dell’immagine generata, supporta `jpeg` (default) e `png`. Solo `doubao-seedream-5.0-lite` supporta.
* `tools`: configurazione degli strumenti da chiamare, attualmente supporta `web_search` (ricerca online). Solo `doubao-seedream-5.0-lite` supporta.
* `callback_url`: URL per ricevere il callback del risultato.
Dopo la selezione, sulla destra viene generato il codice corrispondente, come mostrato:
Cliccando su "Try" è possibile testare; nell'esempio otteniamo il seguente risultato:
```json theme={null}
{
"success": true,
"task_id": "25027ba3-0430-4a1b-91c8-d2297f19ba73",
"trace_id": "8043a9e9-692f-43b0-82f7-5890f798be38",
"data": [
{
"prompt": "a white siamese cat",
"size": "2048x2048",
"image_url": "https://platform.cdn.xhuoapi.ai/seedream/3c060029-69b1-406f-a957-fcd55ddc9386.jpg"
}
]
}
```
Il risultato restituito contiene diversi campi:
* `success`: stato del task di generazione immagine.
* `task_id`: ID del task di generazione.
* `trace_id`: ID di tracciamento del task.
* `data`: lista dei risultati del task di generazione immagine.
* `image_url`: link all’immagine generata.
* `prompt`: prompt utilizzato.
* `size`: dimensione in pixel dell’immagine generata.
Come si vede, otteniamo le informazioni dell’immagine desiderata, basta usare il link `image_url` in `data` per ottenere l’immagine generata da SeeDream.
Se si desidera generare il codice di integrazione corrispondente, è possibile copiarlo direttamente, ad esempio il codice CURL:
```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/seedream/images' \
-H 'accept: application/json' \
-H 'authorization: Bearer ${token}' \
-H 'content-type: application/json' \
-d '{
"action": "generate",
"model": "doubao-seedream-4-0-250828",
"prompt": "a white siamese cat"
}'
```
## Task di modifica immagine
Per modificare un’immagine esistente, è necessario fornire il parametro `image` con il link dell’immagine da modificare.
* `model`: modello usato per la modifica, `doubao-seedream-5.0-lite`, `doubao-seedream-4.5`, `doubao-seedream-4.0` supportano input singolo o multiplo; `doubao-seededit-3.0-i2i` solo singolo.
* `image`: immagine da modificare, singola o multipla.
Esempio di compilazione:
Codice corrispondente:
```python theme={null}
import requests
url = "https://api.xhuoapi.ai/v1/flux/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)
```
Eseguendo si ottiene subito un risultato simile a:
```json theme={null}
{
"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.xhuoapi.ai/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
}
]
}
```
Come si vede, l’effetto generato è una modifica dell’immagine originale, risultato simile a quanto descritto sopra.
## Callback asincrono
Poiché la generazione con SeeDream Images Generation API richiede circa 1-2 minuti, se l’API non risponde a lungo la connessione HTTP rimane aperta, causando consumo di risorse. Per questo l’API supporta anche callback asincroni.
Il flusso è: il client invia la richiesta specificando un campo `callback_url`. L’API risponde immediatamente con un risultato contenente `task_id` che identifica il task. Quando il task è completato, il risultato della generazione viene inviato in POST JSON all’URL `callback_url` specificato, includendo anche `task_id` per correlare i risultati.
Ecco un esempio pratico.
Eseguendo si ottiene subito:
```
{
"task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde"
}
```
Contenuto:
```json theme={null}
{
"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.xhuoapi.ai/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
}
]
}
```
Come si vede, il campo `task_id` consente di correlare i risultati con la richiesta.
## Gestione degli errori
In caso di errore durante la chiamata API, questa restituisce un codice e un messaggio di errore. Esempi:
* `400 token_mismatched`: richiesta errata, parametri mancanti o non validi.
* `400 api_not_implemented`: richiesta errata, parametri mancanti o non validi.
* `401 invalid_token`: non autorizzato, token di autorizzazione mancante o non valido.
* `429 too_many_requests`: troppe richieste, superato il limite di velocità.
* `500 api_error`: errore interno del 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
Con questo documento avete appreso come utilizzare SeeDream Images Generation API per generare immagini tramite prompt. Speriamo che questa guida vi aiuti a integrare e usare al meglio l’API. Per qualsiasi domanda, non esitate a contattare il nostro team di supporto tecnico.