De API voor MetaHuman-hoofden, gebouwd voor batches.

Sturen. Bericht krijgen. Ophalen.

1. Sturen.

   POST /v1/heads met 1 tot 15 foto's van één persoon, als multipart-bestanden of als id's die je eerder uploadde. Voeg een Idempotency-Key toe, en een nieuwe poging maakt of factureert nooit een tweede hoofd.

2. Bericht krijgen.

   Kies hoe: een ondertekende webhook naar je server, een server-sent-eventstream, of een long poll met ?wait=60 voor scripts.

3. Ophalen.

   Vraag om glb, fbx, obj, stl, ply of metahuman_zip, met of zonder ARKit-blendshapes. Je krijgt een ondertekende link waar geen key voor nodig is. Bewaar de id van het hoofd, niet de link. Wat elk formaat bevat

De credits van een mislukt hoofd komen automatisch terug, en error.code zegt waarom.

Een webhook is alles wat je backend nodig heeft.

Maak het hoofd aan, bewaar de id en handel als wij je aanroepen. Dit is de hele integratie, 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);
});

Ingekort om het leesbaar te houden. De referentie EN bevat het volledige request, de handtekeningcontrole en elke fout.

Een cast uit een map, veilig twee keer te draaien.

Een batch bestaat uit veel losse creates. Geef elk een idempotency-key die je afleidt uit je eigen data, zoals de mapnaam, en je kunt het hele script na een crash opnieuw draaien zonder een hoofd twee keer te maken of ervoor te betalen. Laat de webhooks je daarna vertellen welke hoofden klaar zijn.

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

Of laat je agent de integratie schrijven.

De API-referentie, het OpenAPI-bestand en llms.txt zijn geschreven voor mensen en voor taalmodellen. Geef je agent de skill en hij kan rechtstreeks hoofden voor je maken, of het pipelinescript voor jouw stack schrijven en testen.

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.

Gebouwd voor retries, wachtrijen en slechte foto's.

De getallen om omheen te ontwerpen.

De referentie is leidend. Wijkt een getal hier af, dan geldt de referentie.

Het gezicht van een speler, vanaf dag één van de savegame.

Laat spelers hun eigen gezicht meebrengen, of bouw een NPC-cast van acteurs die hebben ingestemd. Elk hoofd is dezelfde mesh met een ander gezicht, dus één rig, één materiaal en één animatieset passen op allemaal. De 52 ARKit-blendshapes kun je aansturen met lipsync of met de camera van de speler.

GLB voor Unity, Godot en het web; FBX en de MetaHuman ZIP voor Unreal. Unreal-automatisering is beschikbaar in vroege toegang: vraag ernaar.

Onze voorwaarden vereisen toestemming van de persoon op de foto en verbieden foto's van kinderen. Bouw dezelfde regel in je eigen flow in.

Gebruik je al een andere API van foto naar MetaHuman?

Maakt je integratie al een hoofd aan, wacht die erop en downloadt die een bestand, dan behoudt die hier zijn vorm. Paden, veldnamen en de bestandsstap verschillen, en de migratiegids zet ze call voor call naast elkaar.

Vragen van developers.

01Is er een sandbox?

Voeg ?dry_run toe aan een create-call. Die controleert het verzoek en geeft een prijsopgave terug, zonder een hoofd te maken of kosten in rekening te brengen.

02Kan ik het aanroepen vanuit een browser of mobiele app?

Nee. Houd de key op je server. Ondertekende upload- en downloadlinks hebben geen key nodig, dus een client kan rechtstreeks uploaden of downloaden.

03Welke SDK's zijn er?

Gewoon HTTP en een OpenAPI 3.1-bestand waaruit je een client kunt genereren. De referentie heeft voorbeelden in curl, Node en Python. De CLI van de skill voor agents is ook één Python-bestand dat je kunt lezen en vanuit scripts kunt aanroepen.

04Hoeveel hoofden kan ik tegelijk maken?

Tot 30 hoofden aanmaken per minuut per account, en elk daarvan loopt via de wachtrij. Voor meer dan 1.000 hoofden: schrijf ons over facturering en capaciteit.

05Is dit de MetaHuman-API van Epic?

Nee. De MetaHuman-API's van Epic besturen MetaHuman Creator via scripts binnen Unreal Engine. FaceNinja maakt het hoofd uit foto's, als webservice, en geeft je de bestanden en de MetaHuman ZIP om in Unreal te importeren.

06Kan er een hoofd worden gemaakt uit een set foto's?

Ja, in beta: reconstructie uit meerdere foto's van één sessie geeft ook de camerapositie en brandpuntsafstand van elke foto terug. Schrijf ons als je het wilt proberen met je eigen opnameset.