Vai al contenuto principale
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, è necessario prima andare alla pagina corrispondente dell’API di Generazione Immagini Flux per richiedere il servizio corrispondente. Una volta entrati nella pagina, cliccare 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 l’API senza costi.

​
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 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:
  • action: l’azione per il compito di generazione dell’immagine.
  • size: le dimensioni del risultato dell’immagine generata.
  • count: il numero di immagini da generare, il valore predefinito è 1, questo parametro è valido solo per i compiti di generazione di immagini, non per i compiti di modifica.
  • prompt: la parola chiave.
  • model: il modello di generazione, predefinito flux-dev.
  • callback_url: l’URL per ricevere il risultato.
Il parametro size ha alcune limitazioni particolari, suddivise principalmente in due tipi: proporzione width x height e proporzione x:y, i dettagli sono i seguenti:
ModelloIntervallo
flux-2-flexSupporta proporzione x >= 64 deve essere un multiplo di 32
flux-2-proSupporta proporzione x >= 64 deve essere un multiplo di 32
flux-2-maxSupporta proporzione x >= 64 deve essere un multiplo di 32
flux-pro-1.1Supporta proporzione 256 <= x <= 1440 deve essere un multiplo di 32
flux-devSupporta proporzione 256 <= x <= 1440 deve essere un multiplo di 32
flux-pro-1.1-ultraNon supporta proporzione, supporta proporzione dell’immagine
flux-kontext-proNon supporta proporzione, supporta proporzione dell’immagine
flux-kontext-maxNon supporta proporzione, supporta proporzione dell’immagine
Proporzioni di riferimento: “1:1”, “16:9”, “21:9”, “3:2”, “2:3”, “4:5”, “5:4”, “3:4”, “4:3”, “9:16”, “9:21”, Dopo aver selezionato, possiamo vedere 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, e abbiamo ottenuto il seguente risultato: 
{
  "success": true,
  "task_id": "226eb763-9eab-4d06-ad57-d59753a03307",
  "trace_id": "089f8b46-0167-4f25-88ee-3c3f88d80e84",
  "data": [
    {
      "prompt": "a white siamese cat",
      "image_url": "https://fal.media/files/lion/NVhtlwwGYQD6HrGaEfrzu_341484fad6d84b21b73f4f8824a3f98a.png",
      "timings": 1752743801
    },
    {
      "prompt": "a white siamese cat",
      "image_url": "https://fal.media/files/monkey/8UEQpFbQCYVOK1wKP3aV0_9bbc26fad64049b18d0244b99ef66ad1.png",
      "timings": 1752743801
    }
  ]
}
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, e dobbiamo solo ottenere l’immagine Flux 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/flux/images' \
-H 'authorization: Bearer {token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "prompt": "a white siamese cat",
  "model": "flux-kontext-pro",
  "count": 2
}'

​
Modifica del Compito di Immagine

Se si desidera modificare un’immagine, prima di tutto il parametro image_url deve contenere il link dell’immagine da modificare, in questo caso action supporta solo edit, e si possono specificare i seguenti contenuti:
  • model: il modello utilizzato per il compito di modifica dell’immagine, attualmente supporta flux-kontext-max, flux-kontext-pro.
  • image_url: caricare l’immagine da modificare.
Esempio di compilazione:

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

Il codice corrispondente: 
import requests

url = "https://api.acedata.cloud/flux/images"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "edit",
    "prompt": "a white siamese cat",
    "model": "flux-kontext-pro",
    "image_url": "https://cdn.acedata.cloud/ytj2qy.png"
}

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": "2a7979ff-1f77-4380-92c6-a2dc37c3b4c8",
  "trace_id": "732b65c0-48d9-49f7-b568-64e5acffe4c0",
  "data": [
    {
      "prompt": "a white siamese cat",
      "image_url": "https://fal.media/files/monkey/aEUXJZ6Faj9YXUCQVs01Q_af0cea56c558441c9ba8df67b200812d.png",
      "timings": 1752744073
    }
  ]
}
Possiamo vedere che l’effetto generato è il risultato della modifica dell’immagine originale, simile al risultato precedente.

​
Callback Asincrono

A causa del tempo relativamente lungo di generazione dell’API Flux Images Generation, che richiede 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. Pertanto, 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 task_id, che rappresenta l’ID del compito corrente. Quando il compito è completato, il risultato dell’immagine generata verrà inviato al callback_url specificato dal client in formato POST JSON, includendo 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, e gli sviluppatori dovrebbero sostituirlo con l’URL del server HTTP che hanno creato. 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, che può essere utilizzato come Webhook; l’esempio qui è https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab. Successivamente, possiamo impostare il campo callback_url sull’URL Webhook sopra menzionato, riempiendo i parametri corrispondenti, come mostrato nell’immagine:

Cliccando su Esegui, possiamo notare che si ottiene immediatamente un risultato, come segue: 
{
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c"
}
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: 
{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": [
    {
      "prompt": "a white siamese cat",
      "image_url": "https://sf-maas-uat-prod.oss-cn-shanghai.aliyuncs.com/outputs/f4f8d407-377a-408a-82d0-427a5a836f09_0.png",
      "seed": 1698551532,
      "timings": {
        "inference": 3.328
      }
    }
  ]
}
Possiamo vedere che nel risultato c’è un campo task_id, gli altri campi sono simili a quelli sopra, e 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

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
Conclusione

Attraverso questo documento, hai appreso 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.