Vai al contenuto principale
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, è necessario prima andare alla pagina corrispondente SeeDream Images Generation API per richiedere il servizio corrispondente. Una volta entrati nella pagina, fare clic sul pulsante “Acquire”, come mostrato nell’immagine: Se non si è ancora effettuato il login o la registrazione, si verrà automaticamente reindirizzati alla pagina di login per registrarsi e accedere. Dopo aver effettuato il login o la registrazione, si tornerà automaticamente alla pagina corrente. Alla prima richiesta, verrà offerto un credito gratuito, che consente di utilizzare gratuitamente questa API.

​
Utilizzo 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 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-4.0.
  • image: informazioni sull’immagine di input, supporta URL o codifica Base64. Tra cui, doubao-seedream-4.5, doubao-seedream-4.0 supportano input di una o più immagini, doubao-seededit-3.0-i2i supporta solo input di un’immagine, doubao-seededit-3.0-t2i non supporta questo parametro.
  • size: specifica le informazioni sulle 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, la forma o l’uso dell’immagine in linguaggio naturale nel prompt, infine il modello determina la dimensione dell’immagine generata. Metodo 2 | Specifica i valori pixel di larghezza e altezza dell’immagine generata: valore predefinito: 2048x2048, a seconda del modello, il valore predefinito varia.
  • seed: seme casuale, utilizzato per controllare la casualità del contenuto generato dal modello. L’intervallo di valori è [-1, 2147483647]. Solo doubao-seedream-3.0-t2i, doubao-seededit-3.0-i2i supportano questo parametro.
  • sequential_image_generation: gruppo di immagini: un insieme di immagini correlate generate in base al contenuto inserito. Solo doubao-seedream-4.5, doubao-seedream-4.0 supportano questo parametro, predefinito disabled.
  • stream: controlla se attivare la modalità di output in streaming. Solo doubao-seedream-4.5, doubao-seedream-4.0 supportano questo parametro, predefinito è false.
  • guidance_scale: grado di coerenza tra il risultato dell’output del modello e il prompt, libertà di generazione dell’immagine, noto anche come peso del testo; maggiore è il valore, minore è la libertà del modello, maggiore è la correlazione con la parola chiave fornita dall’utente. L’intervallo di valori è: [1, 10]. doubao-seedream-3.0-t2i valore predefinito 2.5, doubao-seededit-3.0-i2i valore predefinito 5.5, altri 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.
  • callback_url: URL per il callback dei risultati.
Dopo aver selezionato, si può notare che a destra è stato generato il codice corrispondente, come mostrato nell’immagine:

Cliccando sul pulsante “Try” è possibile effettuare un test, come mostrato nell’immagine sopra, qui abbiamo ottenuto 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.acedata.cloud/seedream/3c060029-69b1-406f-a957-fcd55ddc9386.jpg"
    }
  ]
}
Il risultato restituito ha diversi campi, descritti come segue:
  • success, stato attuale del compito di generazione video.
  • task_id, ID attuale del compito di generazione video.
  • trace_id, ID di tracciamento attuale del video generato.
  • data, elenco dei risultati del compito di generazione dell’immagine.
    • image_url, link attuale del compito di generazione dell’immagine.
    • prompt, parola chiave.
    • size: pixel dell’immagine generata.
Possiamo vedere che abbiamo ottenuto informazioni sull’immagine soddisfacenti, dobbiamo solo ottenere l’immagine SeeDream generata in base all’indirizzo del link dell’immagine in data. Inoltre, se si desidera generare il codice di integrazione corrispondente, è possibile copiarlo direttamente, 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-4-0-250828",
  "prompt": "a white siamese cat"
}'

​
Compito di Modifica Immagine

Se si desidera modificare un’immagine, prima il parametro image deve contenere il link dell’immagine da modificare.
  • model: il modello utilizzato per questo compito di modifica dell’immagine, attualmente supporta doubao-seedream-4.5, doubao-seedream-4.0 supporta input di una o più immagini, doubao-seededit-3.0-i2i supporta solo input di un’immagine.
  • image: caricare l’immagine da modificare, una o più.
Esempio di compilazione:

Codice corrispondente: 
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 del vestito liquido invariati. Cambia il materiale dell'abbigliamento da metallo argentato a completamente trasparente acqua (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, 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": "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"
        }
    ]
}
Si può vedere che l’effetto generato è un effetto di modifica dell’immagine originale, il risultato è simile a quanto sopra.

​
Callback asincrona

Poiché il tempo di generazione dell’API SeeDream Images Generation è relativamente lungo, circa 1-2 minuti, se l’API non risponde per un lungo periodo, la richiesta HTTP manterrà la connessione, causando un ulteriore consumo 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 di informazioni 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 POST JSON, che include anche il campo task_id, in modo che il risultato del compito possa essere associato tramite l’ID. Di seguito, attraverso un esempio, vediamo come operare concretamente. Cliccando 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": "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"
        }
    ]
}
Si può vedere che nel risultato c’è un campo task_id, gli altri campi sono simili a quanto 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

{
  "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 SeeDream Images Generation 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.