Die MetaHuman-Kopf-API, gebaut für Batches.

Senden. Rückmeldung abwarten. Abrufen.

1. Senden.

   POST /v1/heads mit 1 bis 15 Fotos einer Person, als Multipart-Dateien oder als IDs, die Sie zuvor hochgeladen haben. Fügen Sie einen Idempotency-Key hinzu, und eine Wiederholung erstellt oder berechnet nie einen zweiten Kopf.

2. Rückmeldung abwarten.

   Sie wählen, wie: ein signierter Webhook an Ihren Server, ein Server-Sent-Events-Stream oder ein Long Poll mit ?wait=60 für Skripte.

3. Abrufen.

   Fordern Sie glb, fbx, obj, stl, ply oder metahuman_zip an, mit oder ohne ARKit-Blendshapes. Sie erhalten einen signierten Link, der keinen Schlüssel braucht. Speichern Sie die Kopf-ID, nicht den Link. Was jedes Format enthält

Die Credits eines fehlgeschlagenen Kopfs kommen automatisch zurück, und error.code nennt den Grund.

Ein Webhook ist alles, was Ihr Backend braucht.

Erstellen Sie den Kopf, speichern Sie seine ID und handeln Sie, wenn wir Sie aufrufen. Das ist die ganze Integration, 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);
});

Zum Lesen gekürzt. Die Referenz EN enthält die vollständige Anfrage, die Signaturprüfung und jeden Fehler.

Ein Cast aus einem Ordner, sicher zweimal ausführbar.

Ein Batch besteht aus vielen einzelnen Erstellungen. Geben Sie jeder einen Idempotenzschlüssel, den Sie aus Ihren eigenen Daten ableiten, etwa dem Ordnernamen, und Sie können das ganze Skript nach einem Absturz erneut ausführen, ohne einen Kopf doppelt zu erstellen oder zu bezahlen. Lassen Sie sich dann von den Webhooks sagen, welche Köpfe fertig sind.

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

Oder lassen Sie Ihren Agenten die Integration schreiben.

Die API-Referenz, die OpenAPI-Datei und llms.txt sind für Menschen und für Sprachmodelle geschrieben. Geben Sie Ihrem Agenten den Skill, dann kann er direkt Köpfe für Sie erstellen oder das Pipeline-Skript für Ihren Stack schreiben und 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.

Gebaut für Wiederholungen, Warteschlangen und schlechte Fotos.

Die Zahlen, nach denen Sie planen sollten.

Die Referenz ist maßgeblich. Weicht hier eine Zahl ab, gilt die Referenz.

Ein Spielergesicht ab Tag eins des Spielstands.

Lassen Sie Spieler ihr eigenes Gesicht mitbringen, oder bauen Sie einen NPC-Cast aus Darstellern, die eingewilligt haben. Jeder Kopf ist dasselbe Mesh mit einem anderen Gesicht, sodass ein Rig, ein Material und ein Animationsset zu allen passen. Die 52 ARKit-Blendshapes lassen sich per Lippensynchronisation oder über die Kamera des Spielers ansteuern.

GLB für Unity, Godot und das Web; FBX und das MetaHuman ZIP für Unreal. Die Unreal-Automatisierung ist im Early Access: Zugang anfragen.

Unsere Bedingungen verlangen die Einwilligung der Person auf dem Foto und verbieten Fotos von Kindern. Bauen Sie dieselbe Regel in Ihren Ablauf ein.

Sie nutzen schon eine andere Foto-zu-MetaHuman-API?

Wenn Ihre Integration bereits einen Kopf erstellt, auf ihn wartet und eine Datei herunterlädt, behält sie hier ihre Form. Pfade, Feldnamen und der Dateischritt unterscheiden sich, und der Migrationsleitfaden ordnet sie Aufruf für Aufruf zu.

Fragen von Entwicklern.

01Gibt es eine Sandbox?

Hängen Sie ?dry_run an einen Aufruf zum Erstellen an. Er prüft die Anfrage und gibt einen Kostenvoranschlag zurück, ohne einen Kopf zu erstellen oder Ihnen etwas zu berechnen.

02Kann ich sie aus einem Browser oder einer mobilen App aufrufen?

Nein. Behalten Sie den Schlüssel auf Ihrem Server. Signierte Upload- und Download-Links brauchen keinen Schlüssel, deshalb kann ein Client direkt hoch- oder herunterladen.

03Welche SDKs gibt es?

Reines HTTP und eine OpenAPI-3.1-Datei, aus der Sie einen Client generieren können. Die Referenz enthält Beispiele für curl, Node und Python. Die CLI des Skills für KI-Agenten ist außerdem eine einzelne Python-Datei, die Sie lesen und aus Skripten aufrufen können.

04Wie viele Köpfe kann ich gleichzeitig erstellen?

Bis zu 30 Kopf-Erstellungen pro Minute und Konto, und jede läuft in der Warteschlange. Für mehr als 1.000 Köpfe schreiben Sie uns zu Rechnungsstellung und Kapazität.

05Ist das die MetaHuman-API von Epic?

Nein. Die MetaHuman-APIs von Epic steuern MetaHuman Creator per Skript innerhalb von Unreal Engine. FaceNinja erstellt den Kopf aus Fotos, als Webdienst, und gibt Ihnen die Dateien und das MetaHuman ZIP zur Verwendung in Unreal.

06Kann sie einen Kopf aus einer Fotoserie erstellen?

Ja, in der Beta: Die Rekonstruktion aus mehreren Fotos einer Sitzung liefert zusätzlich Kameraposition und Brennweite jedes Fotos. Schreiben Sie uns, wenn Sie es mit Ihrer Aufnahmeserie ausprobieren möchten.