API:et för MetaHuman-huvuden, byggt för batchar.

Skicka. Få svar. Hämta.

1. Skicka.

   POST /v1/heads med 1 till 15 foton av en person, som multipart-filer eller id:n som du har laddat upp först. Lägg till en Idempotency-Key, så skapar eller debiterar ett nytt försök aldrig ett andra huvud.

2. Få svar.

   Välj hur: en signerad webhook till din server, en ström av server-sent events eller en long poll med ?wait=60 för skript.

3. Hämta.

   Be om glb, fbx, obj, stl, ply eller metahuman_zip, med eller utan ARKit-shapes. Du får en signerad länk som inte behöver någon nyckel. Spara huvudets id, inte länken. Vad varje format innehåller

Krediterna för ett misslyckat huvud kommer tillbaka automatiskt, och error.code säger varför.

En webhook är allt din backend behöver.

Skapa huvudet, spara dess id och agera när vi anropar dig. Det här är hela integrationen, i 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);
});

Förkortat för läsbarhet. Referensen EN har hela anropet, signaturkontrollen och varje fel.

En rollbesättning från en mapp, säker att köra två gånger.

En batch är många enskilda skapanden. Ge var och en en idempotensnyckel som du härleder ur dina egna data, till exempel mappnamnet, så kan du köra om hela skriptet efter en krasch utan att göra eller betala för ett huvud två gånger. Låt sedan webhooks tala om vilka huvuden som är klara.

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}"})

Eller låt din agent skriva integrationen.

API-referensen, OpenAPI-filen och llms.txt är skrivna för både människor och språkmodeller. Ge din agent skillen så kan den göra huvuden åt dig direkt, eller skriva och testa pipelineskriptet för din 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.

Byggt för omförsök, köer och dåliga foton.

Siffrorna att designa efter.

Referensen är den som gäller. Om en siffra här avviker gäller referensen.

En spelares ansikte från första dagen i sparfilen.

Låt spelare ta med sitt eget ansikte, eller bygg en NPC-rollbesättning av skådespelare som har samtyckt. Varje huvud är samma mesh med ett annat ansikte, så en rig, ett material och en animationsuppsättning passar alla. De 52 ARKit-shapes tar emot läppsynk eller spelarens kamera.

GLB för Unity, Godot och webben; FBX och MetaHuman ZIP för Unreal. Unreal-automatisering finns i tidig åtkomst: be om åtkomst.

Våra villkor kräver tillstånd från personen på fotot och förbjuder foton av barn. Bygg in samma regel i ditt flöde.

Använder du redan ett annat API för foto till MetaHuman?

Om din integration redan skapar ett huvud, väntar på det och laddar ner en fil behåller den sin form här. Sökvägar, fältnamn och filsteget skiljer sig, och migreringsguiden kopplar ihop dem anrop för anrop.

Frågor från utvecklare.

01Finns det en sandbox?

Lägg till ?dry_run i ett skapandeanrop. Det kontrollerar begäran och returnerar en kostnadsuppgift utan att göra ett huvud eller debitera dig.

02Kan jag anropa det från en webbläsare eller en mobilapp?

Nej. Behåll nyckeln på din server. Signerade uppladdnings- och nedladdningslänkar behöver ingen nyckel, så en klient kan ladda upp eller ladda ner direkt.

03Vilka SDK:er finns?

Vanlig HTTP och en OpenAPI 3.1-fil som du kan generera en klient från. Referensen har exempel i curl, Node och Python. Agentskillens CLI-verktyg är också en enda Python-fil som du kan läsa och anropa från skript.

04Hur många huvuden kan jag göra samtidigt?

Upp till 30 skapade huvuden i minuten per konto, och varje huvud går genom kön. För fler än 1 000 huvuden, skriv till oss om fakturering och kapacitet.

05Är det här Epics MetaHuman-API?

Nej. Epics MetaHuman-API:er skriptar MetaHuman Creator inuti Unreal Engine. FaceNinja gör huvudet av foton, som en webbtjänst, och ger dig filerna och MetaHuman ZIP att ta med in i Unreal.

06Kan det bygga ett huvud av en uppsättning foton?

Ja, i beta: rekonstruktion av flera foton från en session returnerar också varje fotos kameraposition och brännvidd. Skriv till oss om du vill prova med din egen uppsättning foton.