API głów MetaHuman, zbudowane do partii.

Wyślij. Odbierz odpowiedź. Pobierz.

1. Wyślij.

   POST /v1/heads z 1 do 15 zdjęć jednej osoby, jako pliki multipart albo identyfikatory zdjęć wysłanych wcześniej. Dodaj Idempotency-Key, a ponowienie nigdy nie zrobi ani nie obciąży za drugą głowę.

2. Odbierz odpowiedź.

   Wybierz sposób: podpisany webhook na twój serwer, strumień server-sent events albo long poll ?wait=60 dla skryptów.

3. Pobierz.

   Poproś o glb, fbx, obj, stl, ply albo metahuman_zip, z kształtami ARKit lub bez. Dostajesz podpisany link, który nie wymaga klucza. Zapisz identyfikator głowy, nie link. Co zawiera każdy format

Kredyty za nieudaną głowę wracają automatycznie, a error.code podaje powód.

Webhook to wszystko, czego potrzebuje twój backend.

Utwórz głowę, zapisz jej identyfikator i działaj, gdy do ciebie zadzwonimy. To cała integracja, w Pythonie.

# 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);
});

Skrócone dla czytelności. Dokumentacja EN zawiera pełne żądanie, weryfikację podpisu i każdy błąd.

Obsada z folderu, bezpieczna do uruchomienia dwa razy.

Partia to wiele pojedynczych utworzeń. Nadaj każdemu klucz idempotentności wyprowadzony z własnych danych, na przykład z nazwy folderu, a cały skrypt możesz uruchomić ponownie po awarii bez robienia i płacenia za głowę dwa razy. Potem pozwól webhookom powiedzieć, które głowy są gotowe.

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

Albo niech agent napisze integrację.

Dokumentacja API, plik OpenAPI i llms.txt są napisane dla ludzi i dla modeli językowych. Daj agentowi skill, a zrobi głowy bezpośrednio za ciebie albo napisze i przetestuje skrypt pipeline’u dla twojego stosu.

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.

Zbudowane na ponowienia, kolejki i złe zdjęcia.

Liczby, wokół których warto projektować.

Dokumentacja jest źródłem prawdy. Jeśli liczba tutaj się różni, wygrywa dokumentacja.

Twarz gracza od pierwszego dnia pliku zapisu.

Pozwól graczom wnieść własną twarz albo zbuduj obsadę NPC z aktorów, którzy się zgodzili. Każda głowa to ta sama siatka z inną twarzą, więc jeden rig, jeden materiał i jeden zestaw animacji pasują do wszystkich. 52 kształty ARKit przyjmują lip sync albo kamerę gracza.

GLB dla Unity, Godot i sieci; FBX i MetaHuman ZIP dla Unreal. Automatyzacja Unreal jest we wczesnym dostępie: poproś o nią.

Nasz regulamin wymaga zgody osoby ze zdjęcia i zabrania zdjęć dzieci. Wbuduj tę samą zasadę w swój przepływ.

Używasz już innego API ze zdjęcia do MetaHuman?

Jeśli twoja integracja już tworzy głowę, czeka na nią i pobiera plik, zachowuje tu swój kształt. Ścieżki, nazwy pól i krok z plikiem się różnią, a poradnik migracji mapuje je wywołanie po wywołaniu.

Pytania programistów.

01Czy jest sandbox?

Dodaj ?dry_run do wywołania tworzenia. Sprawdza żądanie i zwraca wycenę bez robienia głowy i obciążania cię.

02Czy mogę wywołać to z przeglądarki lub aplikacji mobilnej?

Nie. Trzymaj klucz na serwerze. Podpisane linki do wysyłania i pobierania nie wymagają klucza, więc klient może wysyłać i pobierać bezpośrednio.

03Jakie są SDK?

Zwykły HTTP i plik OpenAPI 3.1, z którego możesz wygenerować klienta. Dokumentacja ma przykłady w curl, Node i Pythonie. CLI skilla agenta to też jeden plik Pythona, który możesz przeczytać i wywoływać ze skryptów.

04Ile głów mogę zrobić naraz?

Do 30 utworzeń głów na minutę na konto, a każde trafia do kolejki. Przy więcej niż 1000 głów napisz do nas w sprawie faktur i przepustowości.

05Czy to API MetaHuman od Epic?

Nie. API MetaHuman od Epic skryptują MetaHuman Creator wewnątrz Unreal Engine. FaceNinja robi głowę ze zdjęć, jako usługa webowa, i daje ci pliki oraz MetaHuman ZIP do zabrania do Unreal.

06Czy zrobi głowę z zestawu zdjęć?

Tak, w wersji Beta: rekonstrukcja z kilku zdjęć z jednej sesji zwraca też pozycję kamery i ogniskową każdego zdjęcia. Napisz do nas, jeśli chcesz wypróbować ją na swoim zestawie zdjęć.