> ## 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. # Integrazione dell'API di Generazione Immagini Flux > Flux Image Generation 集成指南 - XHuoAPI 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](https://api.xhuoapi.ai/documents/6b9197c5-7a3f-4878-a43f-7f94e7e66394) per richiedere il servizio corrispondente. Una volta entrati nella pagina, cliccare sul pulsante "Acquire", come mostrato nell'immagine: ![](https://cdn.xhuoapi.ai/q6ytrc.png) 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: | Modello | Intervallo | | ------------------ | --------------------------------------------------------------------- | | flux-2-flex | Supporta proporzione x >= 64 deve essere un multiplo di 32 | | flux-2-pro | Supporta proporzione x >= 64 deve essere un multiplo di 32 | | flux-2-max | Supporta proporzione x >= 64 deve essere un multiplo di 32 | | flux-pro-1.1 | Supporta proporzione 256 \<= x \<= 1440 deve essere un multiplo di 32 | | flux-dev | Supporta proporzione 256 \<= x \<= 1440 deve essere un multiplo di 32 | | flux-pro-1.1-ultra | Non supporta proporzione, supporta proporzione dell'immagine | | flux-kontext-pro | Non supporta proporzione, supporta proporzione dell'immagine | | flux-kontext-max | Non 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: ```json theme={null} { "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: ```shell theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/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: ```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 = { "action": "edit", "prompt": "a white siamese cat", "model": "flux-kontext-pro", "image_url": "https://cdn.xhuoapi.ai/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: ```json theme={null} { "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/](https://webhook.site/), aprendo questo sito si ottiene un URL Webhook, come mostrato nell'immagine: ![](https://cdn.xhuoapi.ai/cjjfly.png) 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: ![](https://cdn.xhuoapi.ai/v23lot.png) Il contenuto è il seguente: ```json theme={null} { "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 ```json theme={null} { "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.