API-et for MetaHuman-hoder, bygget for batcher.

Send. Få svar. Hent.

1. Send.

   POST /v1/heads med 1 til 15 foto av én person, som multipart-filer eller id-er du har lastet opp først. Legg til en Idempotency-Key, så lager eller fakturerer et nytt forsøk aldri et ekstra hode.

2. Få svar.

   Velg hvordan: en signert webhook til serveren din, en strøm av server-sent events, eller long polling med ?wait=60 for skript.

3. Hent.

   Be om glb, fbx, obj, stl, ply eller metahuman_zip, med eller uten ARKit-blendshapes. Du får en signert lenke som ikke trenger nøkkel. Lagre id-en til hodet, ikke lenken. Hva hvert format inneholder

Kreditene for et mislykket hode kommer tilbake automatisk, og error.code sier hvorfor.

En webhook er alt backenden din trenger.

Opprett hodet, lagre id-en, og handle når vi kaller deg. Dette er hele integrasjonen, 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);
});

Forkortet for lesing. Referansen EN har hele forespørselen, signatursjekken og alle feilene.

Et rollegalleri fra en mappe, trygt å kjøre to ganger.

En batch er mange enkeltopprettinger. Gi hver av dem en idempotency-nøkkel du utleder fra dine egne data, for eksempel mappenavnet, så kan du kjøre hele skriptet på nytt etter en krasj uten å lage eller betale for et hode to ganger. La deretter webhooks fortelle deg hvilke hoder som er ferdige.

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 la agenten din skrive integrasjonen.

API-referansen, OpenAPI-filen og llms.txt er skrevet for både mennesker og språkmodeller. Gi agenten din skillen, så kan den lage hoder for deg direkte, eller skrive og teste pipeline-skriptet for stacken din.

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.

Bygget for nye forsøk, køer og dårlige foto.

Tallene du må planlegge etter.

Referansen er fasit. Hvis et tall her avviker, gjelder referansen.

En spillers ansikt fra dag én i savefilen.

La spillere ta med sitt eget ansikt, eller bygg et NPC-rollegalleri av skuespillere som har samtykket. Hvert hode er det samme meshet med et annet ansikt, så én rigg, ett materiale og ett animasjonssett passer til alle. De 52 ARKit-blendshapes kan styres av lipsync eller spillerens kamera.

GLB for Unity, Godot og nettet; FBX og MetaHuman ZIP for Unreal. Unreal-automatisering er i tidlig tilgang: be om tilgang.

Vilkårene våre krever tillatelse fra personen på fotoet og forbyr foto av barn. Bygg den samme regelen inn i flyten din.

Bruker du allerede et annet API fra foto til MetaHuman?

Hvis integrasjonen din allerede oppretter et hode, venter på det og laster ned en fil, beholder den formen her. Stier, feltnavn og filtrinnet er forskjellige, og migreringsguiden kobler dem kall for kall.

Spørsmål fra utviklere.

01Finnes det en sandkasse?

Legg ?dry_run til et opprettingskall. Det sjekker forespørselen og gir et prisoverslag uten å lage et hode eller belaste deg.

02Kan jeg kalle det fra en nettleser eller en mobilapp?

Nei. Hold nøkkelen på serveren din. Signerte opplastings- og nedlastingslenker trenger ingen nøkkel, så en klient kan laste opp eller ned direkte.

03Hvilke SDK-er finnes?

Vanlig HTTP og en OpenAPI 3.1-fil du kan generere en klient fra. Referansen har eksempler i curl, Node og Python. CLI-en i agent-skillen er også én enkelt Python-fil du kan lese og kalle fra skript.

04Hvor mange hoder kan jeg lage samtidig?

Opptil 30 hodeopprettinger i minuttet per konto, og hvert av dem kjører i køen. For mer enn 1 000 hoder, skriv til oss om fakturering og kapasitet.

05Er dette Epics MetaHuman-API?

Nei. Epics MetaHuman-API-er skripter MetaHuman Creator inne i Unreal Engine. FaceNinja lager hodet fra foto, som en nettjeneste, og gir deg filene og MetaHuman ZIP-en du kan ta med inn i Unreal.

06Kan det bygge et hode fra et sett med foto?

Ja, i beta: rekonstruksjon fra flere foto fra én opptaksøkt gir også kameraposisjonen og brennvidden for hvert foto. Skriv til oss hvis du vil prøve det med opptakssettet ditt.