API'et til MetaHuman-hoveder, bygget til batches.

Send. Få besked. Hent.

1. Send.

   POST /v1/heads med 1 til 15 fotos af én person, som multipart-filer eller id'er, du har uploadet først. Tilføj en Idempotency-Key, så laver eller afregner et nyt forsøg aldrig et ekstra hoved.

2. Få besked.

   Vælg hvordan: en signeret webhook til din server, en strøm af server-sent events eller et ?wait=60-long poll til scripts.

3. Hent.

   Bed om glb, fbx, obj, stl, ply eller metahuman_zip, med eller uden ARKit-blendshapes. Du får et signeret link, der ikke kræver nogen nøgle. Gem hovedets id, ikke linket. Hvad hvert format indeholder

Et mislykket hoveds kreditter kommer tilbage automatisk, og error.code fortæller hvorfor.

En webhook er alt, din backend behøver.

Opret hovedet, gem dets id, og handl, når vi kalder dig. Det er hele 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);
});

Forkortet af hensyn til læsningen. Referencen EN har den fulde forespørgsel, signaturkontrollen og hver fejl.

En rollebesætning fra en mappe, sikker at køre to gange.

En batch er mange enkelte oprettelser. Giv hver en idempotensnøgle, du udleder af dine egne data, for eksempel mappenavnet, og du kan køre hele scriptet igen efter et nedbrud uden at lave eller betale for et hoved to gange. Lad derefter webhooks fortælle dig, hvilke hoveder der er færdige.

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 lad din agent skrive integrationen.

API-referencen, OpenAPI-filen og llms.txt er skrevet både til mennesker og til sprogmodeller. Giv din agent skillen, så kan den lave hoveder direkte for dig eller skrive og teste pipeline-scriptet til 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.

Bygget til genforsøg, køer og dårlige fotos.

Tallene at designe efter.

Referencen er sandhedskilden. Hvis et tal her afviger, gælder referencen.

En spillers ansigt fra første dag i gemmefilen.

Lad spillere medbringe deres eget ansigt, eller byg en NPC-rollebesætning af skuespillere, der har givet samtykke. Hvert hoved er det samme mesh med et andet ansigt, så ét rig, ét materiale og ét animationssæt passer til dem alle. De 52 ARKit-blendshapes tager læbesynkronisering eller spillerens kamera.

GLB til Unity, Godot og nettet; FBX og MetaHuman ZIP til Unreal. Unreal-automatisering er i tidlig adgang: bed om den.

Vores vilkår kræver tilladelse fra personen på fotoet og forbyder fotos af børn. Byg den samme regel ind i dit flow.

Bruger du allerede et andet foto-til-MetaHuman-API?

Hvis din integration allerede opretter et hoved, venter på det og henter en fil, bevarer den sin form her. Stier, feltnavne og filtrinnet er anderledes, og migreringsguiden kortlægger dem kald for kald.

Spørgsmål fra udviklere.

01Findes der en sandbox?

Tilføj ?dry_run til et create-kald. Det tjekker forespørgslen og returnerer et prisoverslag uden at lave et hoved eller opkræve noget af dig.

02Kan jeg kalde det fra en browser eller en mobilapp?

Nej. Hold nøglen på din server. Signerede upload- og download-links kræver ingen nøgle, så en klient kan uploade eller downloade direkte.

03Hvilke SDK'er findes der?

Almindelig HTTP og en OpenAPI 3.1-fil, du kan generere en klient ud fra. Referencen har eksempler i curl, Node og Python. Agent-skillens CLI er også en enkelt Python-fil, du kan læse og kalde fra scripts.

04Hvor mange hoveder kan jeg lave på én gang?

Op til 30 oprettelser af hoveder i minuttet pr. konto, og hver kører i køen. Til mere end 1.000 hoveder, skriv til os om fakturering og kapacitet.

05Er det Epics MetaHuman-API?

Nej. Epics MetaHuman-API'er scripter MetaHuman Creator inde i Unreal Engine. FaceNinja laver hovedet ud fra fotos, som en webtjeneste, og giver dig filerne og MetaHuman ZIP-filen, så du kan tage dem med ind i Unreal.

06Kan det bygge et hoved ud fra et sæt fotos?

Ja, i beta: rekonstruktion ud fra flere fotos fra samme session returnerer også hvert fotos kameraposition og brændvidde. Skriv til os, hvis du vil prøve det med dit optagesæt.