A MetaHuman-fej API, kötegekre építve.

Küldés. Visszajelzés. Letöltés.

1. Küldés.

   POST /v1/heads egy személy 1–15 fotójával, multipart fájlokként vagy előbb feltöltött azonosítókkal. Adj hozzá egy Idempotency-Key fejlécet, és az újrapróbálás soha nem készít és nem számláz második fejet.

2. Visszajelzés.

   Te választod a módját: aláírt webhook a szerveredre, server-sent event stream, vagy ?wait=60 long poll szkriptekhez.

3. Letöltés.

   Kérj glb, fbx, obj, stl, ply vagy metahuman_zip formátumot, ARKit blendshape-ekkel vagy nélkülük. Aláírt linket kapsz, amelyhez nem kell kulcs. A fej azonosítóját tárold el, ne a linket. Mit tartalmaz mindegyik formátum

A sikertelen fej kreditje automatikusan visszajár, az error.code pedig megmondja az okot.

Egy webhook elég a backendednek.

Hozd létre a fejet, tárold el az azonosítóját, és cselekedj, amikor hívunk. Ez a teljes integráció, Pythonban.

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

Olvashatóság kedvéért lerövidítve. A teljes kérést, az aláírás-ellenőrzést és az összes hibát lásd a referenciában EN.

Szereplőgárda egy mappából, kétszer is biztonságosan futtatható.

A köteg sok önálló létrehozás. Adj mindegyiknek egy idempotencia-kulcsot, amelyet a saját adataidból származtatsz, például a mappa nevéből, és az egész szkriptet újrafuttathatod egy összeomlás után anélkül, hogy kétszer készítenél vagy fizetnél egy fejért. Aztán a webhookok megmondják, mely fejek készültek el.

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

Vagy írassa meg az ügynököd az integrációt.

Az API-referencia, az OpenAPI-fájl és az llms.txt emberekre és nyelvi modellekre is szabva van. Add oda az ügynöködnek a skillt, és közvetlenül készíthet neked fejeket, vagy megírhatja és letesztelheti a pipeline-szkriptet a te stackedhez.

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.

Újrapróbálásra, sorokra és rossz fotókra építve.

A számok, amelyekhez igazodnod kell.

A referencia a mérvadó. Ha egy itteni szám eltér, a referencia az érvényes.

A játékos arca a mentés első napjától.

Hagyd, hogy a játékosok a saját arcukat hozzák, vagy építs NPC-szereplőgárdát beleegyező színészekből. Minden fej ugyanaz a fejháló más arccal, ezért egyetlen rig, egyetlen anyag és egyetlen animációkészlet illik mindegyikhez. Az 52 ARKit blendshape lip syncet vagy a játékos kameráját fogadja.

GLB: Unity, Godot és web; FBX és MetaHuman ZIP: Unreal. Az Unreal-automatizálás korai hozzáférésben van: kérd el.

A feltételeink megkövetelik a fotón szereplő személy engedélyét, és tiltják a gyerekekről készült fotókat. Építsd be ugyanezt a szabályt a saját folyamatodba.

Már használsz másik fotóból MetaHuman-fejet készítő API-t?

Ha az integrációd már létrehoz egy fejet, megvárja, és letölt egy fájlt, itt is megtartja az alakját. Az útvonalak, a mezőnevek és a fájllépés eltér, az átállási útmutató pedig hívásról hívásra megfeleltet.

Fejlesztői kérdések.

01Van sandbox?

Fűzd a ?dry_run paramétert a létrehozási híváshoz. Ellenőrzi a kérést, és árajánlatot ad vissza fej készítése és terhelés nélkül.

02Hívhatom böngészőből vagy mobilalkalmazásból?

Nem. A kulcsot tartsd a szervereden. Az aláírt feltöltési és letöltési linkekhez nem kell kulcs, így egy kliens közvetlenül tölthet fel vagy le.

03Milyen SDK-k vannak?

Sima HTTP, és egy OpenAPI 3.1 fájl, amiből klienst generálhatsz. A referenciában curl, Node és Python példák vannak. Az ügynök-skill CLI-je is egyetlen Python-fájl, amelyet elolvashatsz és szkriptekből hívhatsz.

04Hány fejet készíthetek egyszerre?

Fiókonként percenként legfeljebb 30 fej létrehozása, és mindegyik a sorban fut. 1000 fejnél többhöz írj nekünk a számlázásról és a kapacitásról.

05Ez az Epic MetaHuman API-ja?

Nem. Az Epic MetaHuman API-jai az Unreal Engine-en belül a MetaHuman Creator használatát szkriptelik. A FaceNinja webszolgáltatásként fotókból készíti a fejet, és átadja a fájlokat és a MetaHuman ZIP-et, amelyeket az Unreal Engine-be vihetsz.

06Fel tud építeni egy fejet egy fotósorozatból?

Igen, Beta állapotban: egy munkamenet több fotójából történő rekonstrukció az egyes fotók kamerapozícióját és gyújtótávolságát is visszaadja. Írj nekünk, ha ki szeretnéd próbálni a saját felvételsorozatoddal.