API face swap: come aggiungere lo scambio di volti alla tua app

Un'API di face swap permette alla tua app di inserire il volto di una persona in un'altra foto con una sola richiesta HTTP. Questa guida mostra la richiesta in curl, JavaScript e Python, come gestire i lavori lunghi e le foto di gruppo, cosa significano gli errori, quanto costa e come usarla in modo responsabile.

Team Morfran · 4 min di lettura · aggiornato il 22 nov 2026

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:

  1. Un account Morfran. I nuovi account ricevono 50 crediti gratuiti, sufficienti per dieci scambi di volti singoli.
  2. 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.
  3. 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.