L'API per teste MetaHuman, pensata per i batch.

Invia. Ricevi risposta. Scarica.

1. Invia.

   POST /v1/heads con da 1 a 15 foto di una persona, come file multipart o come id che hai caricato prima. Aggiungi un Idempotency-Key, e un nuovo tentativo non crea né addebita mai una seconda testa.

2. Ricevi risposta.

   Scegli come: un webhook firmato verso il tuo server, un flusso di server-sent event, o un long poll ?wait=60 per gli script.

3. Scarica.

   Richiedi glb, fbx, obj, stl, ply o metahuman_zip, con o senza forme ARKit. Ricevi un link firmato che non richiede chiave. Salva l'id della testa, non il link. Cosa contiene ogni formato

I crediti di una testa fallita tornano automaticamente, e error.code dice perché.

A un backend basta un webhook.

Crea la testa, salva il suo id e agisci quando ti chiamiamo. Questa è l'intera integrazione, in Python.

# when the user confirms their photos
head = api.post("/v1/heads", files=photos,
                data={"webhook_url": "https://you.example/hooks/faceninja"},
                headers={"Idempotency-Key": str(uuid4())}).json()
save(user, head["id"])

# later, FaceNinja calls you
@app.post("/hooks/faceninja")
def on_head(event = verified(request)):        # check FaceNinja-Signature first
    if event["type"] == "head.completed":
        link = api.post(f"/v1/heads/{event['data']['id']}/files",
                        json={"format": "glb", "arkit": True}).json()
        store_on_your_cdn(link["url"])

// when the user confirms their photos
const form = new FormData();
for (const p of photos) form.append("photos", p);
form.append("webhook_url", "https://you.example/hooks/faceninja");
const head = await api.post("/v1/heads", form,
  { headers: { "Idempotency-Key": crypto.randomUUID() } });
await save(user, head.id);

// later, FaceNinja calls you
app.post("/hooks/faceninja", async (req, res) => {
  const event = verified(req);                 // check FaceNinja-Signature first
  if (event.type === "head.completed") {
    const link = await api.post(`/v1/heads/${event.data.id}/files`,
      { format: "glb", arkit: true });
    await storeOnYourCdn(link.url);
  }
  res.sendStatus(204);
});

Accorciato per la lettura. Il riferimento EN contiene la richiesta completa, il controllo della firma e ogni errore.

Un cast da una cartella, sicuro da eseguire due volte.

Un batch è fatto di tante creazioni singole. Dai a ognuna una chiave di idempotenza che ricavi dai tuoi dati, per esempio il nome della cartella, e puoi rieseguire l'intero script dopo un crash senza creare né pagare due volte una testa. Poi lascia che siano i webhook a dirti quali teste sono pronte.

for person in sorted(Path("cast").iterdir()):            # one folder per person
    photos = [("photos", open(p, "rb")) for p in sorted(person.glob("*.jpg"))]
    api.post("/v1/heads", files=photos,
             data={"name": person.name, "webhook_url": HOOK},
             headers={"Idempotency-Key": f"cast-2026-10/{person.name}"})

Oppure lascia che sia il tuo agente a scrivere l'integrazione.

Il riferimento API, il file OpenAPI e llms.txt sono scritti per le persone e per i modelli linguistici. Dai al tuo agente la skill e potrà creare teste direttamente per te, oppure scrivere e testare lo script di pipeline per il tuo stack.

Read https://faceninja.net/llms.txt and https://faceninja.net/skill/SKILL.md. Write a Python script for our pipeline: for each new folder in ./incoming, create one FaceNinja head from its photos with an Idempotency-Key derived from the folder name and a webhook_url I give you. Add a small web handler that checks the FaceNinja-Signature header, and on head.completed downloads the FBX to ./heads/<folder name>; on head.failed it logs error.code. Read the API key from FACENINJA_API_KEY. Don't run anything against my account until I say so.

Pensata per retry, code e foto sbagliate.

I numeri attorno a cui progettare.

Il riferimento è la fonte di verità. Se un numero qui è diverso, vale il riferimento.

Il volto di un giocatore dal primo giorno del salvataggio.

Lascia che i giocatori portino il proprio volto, oppure crea un cast di NPC con attori che hanno dato il consenso. Ogni testa è la stessa mesh con un volto diverso, quindi un solo rig, un solo materiale e un solo set di animazioni vanno bene per tutte. Le 52 forme ARKit gestiscono il lip sync o la camera del giocatore.

GLB per Unity, Godot e il web; FBX e MetaHuman ZIP per Unreal. L'automazione per Unreal è in accesso anticipato: richiedila.

I nostri termini richiedono il permesso della persona nella foto e vietano le foto di bambini. Costruisci la stessa regola nel tuo flusso.

Usi già un'altra API da foto a MetaHuman?

Se la tua integrazione già crea una testa, la aspetta e scarica un file, qui mantiene la stessa struttura. Percorsi, nomi dei campi e il passaggio del file cambiano, e la guida alla migrazione li mappa chiamata per chiamata.

Domande degli sviluppatori.

01C'è una sandbox?

Aggiungi ?dry_run a una chiamata di creazione. Verifica la richiesta e restituisce un preventivo senza creare una testa né addebitarti nulla.

02Posso chiamarla da un browser o da un'app mobile?

No. Tieni la chiave sul tuo server. I link firmati di caricamento e download non richiedono chiave, quindi un client può caricare o scaricare direttamente.

03Quali SDK ci sono?

HTTP semplice e un file OpenAPI 3.1 da cui puoi generare un client. Il riferimento ha esempi in curl, Node e Python. Anche la CLI della skill per agenti è un unico file Python che puoi leggere e chiamare dagli script.

04Quante teste posso creare insieme?

Fino a 30 creazioni di teste al minuto per account, e ciascuna passa dalla coda. Per più di 1000 teste, scrivici per fatturazione e capacità.

05È l'API MetaHuman di Epic?

No. Le API MetaHuman di Epic gestiscono con script MetaHuman Creator dentro Unreal Engine. FaceNinja crea la testa dalle foto, come servizio web, e ti consegna i file e il MetaHuman ZIP da portare in Unreal.

06Può creare una testa da un set di foto?

Sì, in Beta: la ricostruzione da più foto di una stessa sessione restituisce anche la posizione della camera e la lunghezza focale di ogni foto. Scrivici se vuoi provarla con il tuo set di scatti.