Skip to main content
Questo documento introduce un’integrazione dell’API di Generazione Immagini Flux, che consente di generare immagini ufficiali di Flux tramite l’inserimento di parametri personalizzati.

​
Procedura di Richiesta

Per utilizzare l’API di Generazione Immagini Flux, prima di tutto vai al Pannello di Controllo di Ace Data Cloud 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 a effettuare il login; 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 separato per ogni servizio. La prima richiesta ti darà un credito gratuito, per un’esperienza senza costi; quando il credito è insufficiente, puoi ricaricare il saldo generale nel pannello di controllo.
📘 Documentazione completa: API di Generazione Immagini Flux →

​
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 che desideri ricevere, 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:
  • action: l’azione per il compito di generazione dell’immagine.
  • size: le dimensioni del risultato dell’immagine generata. Le serie flux-2-flex / flux-2-pro / flux-2-max devono ricevere il rapporto dell’immagine (ad esempio 1:1, 16:9), non accettano dimensioni in pixel come 1024x1024, e il valore predefinito restituirà 400.
  • count: il numero di immagini da generare, il valore predefinito è 1, questo parametro è valido solo per i compiti di generazione di immagini, non è valido per i compiti di modifica.
  • prompt: la parola chiave.
  • model: il modello di generazione, predefinito flux-dev; l’ultimo flagship è flux-2-pro, flux-2-max (qualità dell’immagine più alta, deve essere abbinato al rapporto dell’immagine size).
  • callback_url: l’URL per il quale è necessario il risultato del callback.
  • async: opzionale, se impostato su true, l’interfaccia restituisce immediatamente task_id, senza necessità di fornire callback_url, successivamente puoi ottenere i risultati tramite l’interfaccia di query del compito corrispondente.
Il parametro size ha alcune restrizioni particolari, principalmente suddivise in due tipi: rapporto width x height e rapporto immagine x:y, i dettagli sono i seguenti: Rapporti immagine di riferimento: “21:9”, “16:9”, “4:3”, “3:2”, “1:1”, “2:3”, “3:4”, “9:16”, “9:21”. Dopo aver selezionato i parametri, il codice corrispondente verrà generato automaticamente a destra. Prima di copiare, assicurati che l’intestazione di autorizzazione utilizzi la tua chiave API, le credenziali reali non dovrebbero apparire nella documentazione e negli screenshot. Clicca sul pulsante “Try” per effettuare un test, qui abbiamo ottenuto il seguente risultato:
Il risultato restituito ha diversi campi, descritti 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 video generato attuale.
  • data, l’elenco dei risultati del compito di generazione dell’immagine attuale.
    • image_url, il link del compito di generazione dell’immagine attuale.
    • prompt, la parola chiave.
Possiamo vedere che abbiamo ottenuto informazioni soddisfacenti sull’immagine, dobbiamo solo ottenere l’immagine Flux generata in base all’indirizzo del link dell’immagine in data. Inoltre, se desideri generare il codice di integrazione corrispondente, puoi semplicemente copiarlo, ad esempio il codice CURL è il seguente:

​
Modifica del Compito di Immagine

Se desideri modificare un’immagine specifica, prima di tutto il parametro image_url deve contenere il link dell’immagine da modificare, in questo caso action supporta solo edit, e puoi specificare i seguenti contenuti:
  • model: il modello utilizzato per il compito di modifica dell’immagine, supporta flux-dev, flux-pro, flux-kontext-pro, flux-kontext-max, flux-2-flex, flux-2-pro, flux-2-max.
  • image_url: carica l’immagine da modificare.
Esempio di compilazione:

Dopo aver completato la compilazione, il codice generato automaticamente è il seguente:

Codice corrispondente:
Cliccando su “Esegui”, puoi scoprire che riceverai immediatamente un risultato, come segue:
Si può vedere che l’effetto generato è l’effetto di modifica dell’immagine originale, il risultato è simile a quanto descritto sopra.

​
Callback Asincrono

Poiché il tempo di generazione dell’API Flux 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 generale è: 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 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, vediamo un esempio per capire come operare concretamente. Innanzitutto, il callback Webhook è un servizio in grado di ricevere richieste HTTP, gli sviluppatori dovrebbero sostituirlo con l’URL del server HTTP che hanno costruito. Qui, per comodità di dimostrazione, utilizziamo un sito Web pubblico di esempio per Webhook https://webhook.site/, aprendo questo sito si ottiene un URL Webhook, come mostrato nell’immagine: Copia questo URL, può essere utilizzato come Webhook, l’esempio qui è https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab. Successivamente, possiamo impostare il campo callback_url su questo URL Webhook, riempiendo i parametri corrispondenti, il contenuto specifico è mostrato nell’immagine:

Cliccando su Esegui, si può notare che si ottiene immediatamente un risultato, come segue:
Dopo un momento, possiamo osservare il risultato dell’immagine generata su https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab, come mostrato nell’immagine: Il contenuto è il seguente:
Si può vedere che nel risultato c’è un campo task_id, gli altri campi sono simili a quanto descritto 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 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

​
Conclusione

Attraverso questo documento, hai compreso come utilizzare l’API Flux 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.