Istruzioni per l'integrazione con SeeDream Images Generation API

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. 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:

{
  "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:

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:

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:

{
    "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:

{
    "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

{
  "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.

Documentation Index

​Procedura di richiesta

​Uso base

​Task di modifica immagine

​Callback asincrono

​Gestione degli errori

​Esempio di risposta di errore

​Conclusione