Vai al contenuto principale
La principale funzionalità dell’API Face Swap è quella di sostituire il volto presente in un’immagine sorgente con il volto presente in un’immagine di destinazione, fornendo entrambe le immagini come input. Questo documento fornirà dettagliate istruzioni per l’integrazione dell’API Face Swap, aiutandoti a integrare facilmente e sfruttare appieno le potenti funzionalità di questa API. Con l’API Face Swap, puoi facilmente realizzare la sostituzione del volto dell’immagine di destinazione con quello dell’immagine sorgente.

​
Processo di richiesta

Per utilizzare l’API Face Swap, è necessario prima andare alla pagina di richiesta Face Swap API per richiedere il servizio corrispondente. Una volta entrati nella pagina, clicca sul pulsante “Acquire”, come mostrato nell’immagine: Pagina di richiesta Se non sei ancora loggato o registrato, verrai automaticamente reindirizzato alla pagina di login che ti invita a registrarti e accedere. Dopo aver effettuato il login o la registrazione, verrai automaticamente riportato alla pagina corrente. Alla prima richiesta, verrà fornito un credito gratuito, che ti consente di utilizzare l’API senza costi.

​
Esempio di richiesta

Utilizziamo due immagini come esempio per dimostrare come utilizzare questa API. Supponiamo che l’immagine sorgente sia quella mostrata di seguito:

L’immagine di destinazione è:

Ora dimostriamo come sostituire il volto dell’immagine di destinazione con quello dell’immagine sorgente.

​
Impostazione dell’intestazione della richiesta e del corpo della richiesta

Request Headers includono:
  • accept: specifica di ricevere la risposta in formato JSON, qui si compila con application/json.
  • authorization: la chiave per chiamare l’API, che può essere selezionata direttamente dopo la richiesta.
Request Body include:
  • source_image_url: il link all’immagine sorgente caricata.
  • target_image_url: il link all’immagine di destinazione caricata.
  • timeout: opzionale, il tempo di timeout per l’elaborazione (in secondi), il timeout restituirà direttamente.
Impostato come mostrato nell’immagine seguente:

​
Esempio di codice

Si può notare che, sul lato destro della pagina, sono già stati generati automaticamente vari codici in diverse lingue, come mostrato nell’immagine:

Alcuni esempi di codice sono i seguenti:

​
CURL

curl -X POST 'https://api.acedata.cloud/face/swap' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "source_image_url": "https://cdn.acedata.cloud/n1lmd8.png",
  "target_image_url": "https://cdn.acedata.cloud/3np95r.png"
}'

​
Python

import requests

url = "https://api.acedata.cloud/face/swap"

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

payload = {
    "source_image_url": "https://cdn.acedata.cloud/n1lmd8.png",
    "target_image_url": "https://cdn.acedata.cloud/3np95r.png"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

​
Esempio di risposta

Se la richiesta ha successo, l’API restituirà informazioni sul risultato dell’immagine con il volto sostituito. Ad esempio: 
{
  "image_url": "https://platform.cdn.acedata.cloud/face/4b13bdeb-1b19-4ea5-bddf-c2da14ba72e3.png",
  "image_width": 2008,
  "image_height": 1942,
  "image_size": 4006213,
  "task_id": "4b13bdeb-1b19-4ea5-bddf-c2da14ba72e3"
}
Si può notare che nel risultato è presente un campo image_url, che contiene il link all’immagine risultante dalla sostituzione del volto dell’immagine di destinazione con quello dell’immagine sorgente. Altre informazioni sono mostrate nell’immagine seguente:
  • image_url, il link all’immagine generata.
  • image_width, la larghezza dell’immagine generata.
  • image_height, l’altezza dell’immagine generata.
  • image_size, la dimensione dell’immagine generata.
  • task_id, l’ID del compito di generazione.
Il risultato dell’immagine generata è:

È evidente che l’immagine ha già sostituito con successo il volto dell’immagine di destinazione con quello dell’immagine sorgente.

​
Callback asincrona

Poiché il tempo di generazione di Face Swap è relativamente lungo, circa 1-2 minuti, se l’API non risponde per un lungo periodo, la richiesta HTTP manterrà la connessione, causando un consumo aggiuntivo di risorse di sistema. Pertanto, questa API offre anche supporto per callback asincroni. Il processo 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 della generazione di Face Swap verrà inviato al callback_url specificato dal client in formato JSON POST, 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/3b76eba5-4573-432a-b607-3000b87afc06. Successivamente, possiamo impostare il campo callback_url con l’URL Webhook sopra menzionato, riempiendo i parametri corrispondenti, come mostrato nell’immagine:

Cliccando su Esegui, si può notare che si ottiene immediatamente un risultato, come segue: 
{
  "task_id": "9cba9d36-3b14-43c9-85b6-86f6dfc3b096"
}
Dopo un momento, possiamo osservare il risultato della generazione di Face Swap su https://webhook.site/3b76eba5-4573-432a-b607-3000b87afc06, come mostrato nell’immagine: Il contenuto è il seguente: 
{
  "success": true,
  "task_id": "9cba9d36-3b14-43c9-85b6-86f6dfc3b096",
  "image_url": "https://platform.cdn.acedata.cloud/face/9cba9d36-3b14-43c9-85b6-86f6dfc3b096.png",
  "image_width": 2008,
  "image_height": 1942,
  "image_size": 4006481
}
Si può notare che nel risultato è presente un campo task_id, e gli altri campi sono simili a quelli menzionati in precedenza, consentendo di associare il compito tramite questo campo.

​
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 appreso come utilizzare l’API Face Swap per sostituire il volto dell’immagine di destinazione con il volto dell’immagine sorgente. 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.