Cosa fa un'API di scambio di volti
Un'API di face swap riceve due immagini e ne restituisce una nuova. L'immagine sorgente mostra il volto che vuoi usare. L'immagine di destinazione è la foto che vuoi modificare. L'API trova il volto nella destinazione, lo sostituisce con il volto della sorgente e uniforma tono della pelle, luce e angolazione, così il risultato sembra un'unica foto.
Gli sviluppatori la usano per cose come biglietti d'auguri personalizzati, campagne del tipo "mettiti sul poster", strumenti per avatar e profili, personaggi di giochi e app photo booth agli eventi. Invece di addestrare e ospitare i tuoi modelli, invii una richiesta HTTP e ricevi un'immagine.
Prima di iniziare
Ti servono tre cose:
- Un account Morfran. I nuovi account ricevono 50 crediti gratuiti, sufficienti per dieci scambi di volti singoli.
- Una chiave API. Creala nella tua dashboard alla voce Chiavi API. Tienila sul tuo server e non inserirla mai nel codice del browser o di un'app mobile.
- Due URL pubblici di immagini. JPG, PNG o WebP. La sorgente dovrebbe mostrare un volto chiaro, rivolto più o meno verso la fotocamera.
Ogni richiesta invia la chiave nell'header X-API-Key. L'URL di base è https://api.morfran.com.
Il tuo primo scambio di volti con curl
curl -X POST https://api.morfran.com/v1/face-swap \
-H "X-API-Key: $MORFRAN_KEY" \
-H "Content-Type: application/json" \
-d '{"SourceImageUrl":"https://example.com/face.jpg","TargetImageUrl":"https://example.com/photo.jpg"}'
Di default la chiamata è sincrona: l'API attende il risultato (fino a circa 60 secondi) e restituisce una risposta JSON con un link all'immagine finita su cdn.morfran.com, più i crediti usati. Scarica subito l'immagine, perché i risultati vengono eliminati dopo un'ora.
La stessa richiesta in JavaScript (Node.js)
const res = await fetch("https://api.morfran.com/v1/face-swap", {
method: "POST",
headers: {
"X-API-Key": process.env.MORFRAN_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
SourceImageUrl: "https://example.com/face.jpg",
TargetImageUrl: "https://example.com/photo.jpg",
}),
});
const data = await res.json();
console.log(res.status, data);
Esegui questo codice sul tuo server, non nel browser, così la tua chiave resta privata.
La stessa richiesta in Python
import os
import requests
res = requests.post(
"https://api.morfran.com/v1/face-swap",
headers={"X-API-Key": os.environ["MORFRAN_KEY"]},
json={
"SourceImageUrl": "https://example.com/face.jpg",
"TargetImageUrl": "https://example.com/photo.jpg",
},
timeout=90,
)
print(res.status_code, res.json())
Lavori lunghi: usa la modalità asincrona
Se la tua app non deve restare in attesa su una richiesta aperta, aggiungi ?async=true all'URL. L'API risponde subito con un id del task. Poi leggi il risultato con GET /v1/face-swap/{taskId} ogni pochi secondi finché non è pronto. Funziona bene dietro una coda di lavori, o quando il tuo server ha un timeout delle richieste breve.
Foto di gruppo: scambia fino a otto volti
Per una foto di squadra o di famiglia, usa POST /v1/face-swap/group. Cambia fino a otto volti in una sola chiamata; MaxFaces imposta il limite. Uno scambio di gruppo costa 10 crediti, uno singolo 5 crediti. L'elenco completo dei campi è nella documentazione dell'API e nello schema OpenAPI.
Gestisci errori e crediti
- 401: la chiave API manca o è sbagliata. Controlla l'header
X-API-Key. - 402: crediti insufficienti. Acquista un pacchetto di crediti nella tua dashboard.
- 422: non è stato trovato nessun volto. Chiedi all'utente una foto più chiara con un solo volto.
Le richieste non riuscite non vengono addebitate. I crediti vengono scalati solo per le immagini finite, quindi un nuovo tentativo dopo un 422 non costa il doppio. Puoi leggere il tuo saldo in qualsiasi momento con GET /v1/credits/balance, che è gratuito.
Consigli per risultati migliori
- Usa un volto sorgente chiaro. Una sola persona, rivolta verso la fotocamera, occhi aperti, niente occhiali da sole, buona luce.
- Abbina l'angolazione. Un volto che guarda dritto davanti si fonde meglio in una destinazione in cui anche la persona guarda più o meno verso la fotocamera.
- Mantieni i volti abbastanza grandi. Un volto largo solo pochi pixel nella destinazione non si può scambiare bene.
- Una luce simile aiuta. Un volto fotografato alla luce del giorno appare più naturale in una foto di destinazione alla luce del giorno.
- Fai prove con le tue immagini reali. Usa qualche credito gratuito su foto simili a quelle che caricheranno i tuoi utenti.
Consenso e privacy
Scambia solo il volto di qualcuno che ha dato il suo consenso. Non usare lo scambio di volti per ingannare le persone, per impersonare qualcuno o per creare contenuti che danneggiano una persona reale. Se pubblichi i risultati, indica che sono generati con l'IA. Le immagini caricate e i risultati vengono eliminati dal nostro storage entro un'ora e non li usiamo per addestrare modelli di IA. Gli abusi possono essere segnalati tramite la pagina dei contatti e vengono gestiti entro 48 ore.
Usala da un agente IA
Lo stesso scambio di volti è disponibile sul server MCP di Morfran all'indirizzo https://api.morfran.com/mcp, così assistenti come Claude possono chiamarlo con la tua chiave API. La configurazione è descritta nella sezione MCP della documentazione.
Domande
Quanto costa l'API di scambio di volti?
Uno scambio di volti singolo costa 5 crediti e uno scambio di gruppo (fino a otto volti) costa 10 crediti. I nuovi account ricevono 50 crediti gratuiti. Dopo acquisti pacchetti di crediti; non c'è nessun abbonamento. Vedi i prezzi per i pacchetti.
Quanto tempo richiede uno scambio di volti?
La maggior parte dei risultati arriva entro l'attesa sincrona di circa 60 secondi. Per lavori lunghi o timeout del server brevi, usa ?async=true e leggi il risultato con l'id del task.
Posso inviare le immagini in base64 invece che come URL?
Gli esempi qui usano URL pubblici, che è il modo più semplice. Lo schema OpenAPI elenca tutti i campi di input accettati dall'endpoint.
Per quanto tempo vengono conservati i risultati?
Le immagini caricate e i risultati vengono eliminati entro un'ora. Salva l'immagine risultante dalla tua parte appena la ricevi.
Posso provarla senza scrivere codice?
Sì. Accedi e apri il Playground. Esegue lo stesso scambio di volti nel browser e mostra la richiesta API corrispondente.