ה-API לראשי MetaHuman, בנוי לאצוות.

שולחים. מקבלים הודעה. מורידים.

1. שולחים.

   POST /v1/heads עם 1 עד 15 תמונות של אדם אחד, כקובצי multipart או כמזהים שהועלו קודם. מוסיפים Idempotency-Key, וניסיון חוזר לעולם לא יוצר ולא מחייב ראש שני.

2. מקבלים הודעה.

   בוחרים איך: webhook חתום לשרת שלכם, זרם server-sent events, או long poll עם ?wait=60 לסקריפטים.

3. מורידים.

   מבקשים glb, fbx, obj, stl, ply או metahuman_zip, עם צורות ARKit או בלעדיהן. מקבלים קישור חתום שלא דורש מפתח. שומרים את מזהה הראש, לא את הקישור. מה כל פורמט מכיל

הקרדיטים של ראש שנכשל חוזרים אוטומטית, ו-error.code מסביר למה.

webhook הוא כל מה שהשרת שלכם צריך.

יוצרים את הראש, שומרים את המזהה שלו ופועלים כשאנחנו קוראים אליכם. זו האינטגרציה כולה, ב-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);
});

מקוצר לקריאה. בתיעוד EN יש את הבקשה המלאה, את בדיקת החתימה ואת כל השגיאות.

קאסט מתיקייה, בטוח להריץ פעמיים.

אצווה היא הרבה יצירות בודדות. נותנים לכל אחת מפתח idempotency שנגזר מהנתונים שלכם, כמו שם התיקייה, ואפשר להריץ מחדש את כל הסקריפט אחרי קריסה בלי ליצור ראש או לשלם עליו פעמיים. אחר כך ה-webhooks מודיעים אילו ראשים מוכנים.

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

או שהסוכן כותב את האינטגרציה.

תיעוד ה-API, קובץ ה-OpenAPI ו-llms.txt כתובים לאנשים ולמודלי שפה. נותנים לסוכן את המיומנות והוא יכול ליצור ראשים ישירות, או לכתוב ולבדוק את סקריפט צינור העבודה עבור הסטאק שלכם.

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.

בנוי לניסיונות חוזרים, לתורים ולתמונות גרועות.

המספרים שסביבם מתכננים.

התיעוד הוא מקור האמת. אם מספר כאן שונה, התיעוד קובע.

הפנים של שחקן ביום הראשון של קובץ השמירה.

נותנים לשחקנים להביא את הפנים שלהם, או בונים קאסט NPC משחקנים שהסכימו. כל ראש הוא אותה רשת עם פנים אחרות, כך שריג אחד, חומר אחד וסט אנימציות אחד מתאימים לכולם. 52 צורות ה-ARKit מקבלות סנכרון שפתיים או את המצלמה של השחקן.

GLB ל-Unity, ל-Godot ולרשת; FBX ו-MetaHuman ZIP ל-Unreal. אוטומציית Unreal נמצאת בגישה מוקדמת: לבקשת גישה.

התנאים שלנו דורשים אישור מהאדם שבתמונה ואוסרים תמונות של ילדים. בונים את אותו כלל בתוך התהליך שלכם.

כבר משתמשים ב-API אחר מתמונה ל-MetaHuman?

אם האינטגרציה שלכם כבר יוצרת ראש, ממתינה לו ומורידה קובץ, היא שומרת כאן על הצורה שלה. הנתיבים, שמות השדות ושלב הקובץ שונים, ומדריך המעבר ממפה אותם קריאה אחר קריאה.

שאלות של מפתחים.

01יש סביבת בדיקות (sandbox)?

מוסיפים ?dry_run לקריאת יצירה. היא בודקת את הבקשה ומחזירה הצעת מחיר בלי ליצור ראש ובלי לחייב.

02אפשר לקרוא לו מדפדפן או מאפליקציית מובייל?

לא. המפתח נשאר בשרת שלכם. קישורי העלאה והורדה חתומים לא דורשים מפתח, ולכן לקוח יכול להעלות או להוריד ישירות.

03אילו SDK יש?

HTTP פשוט וקובץ OpenAPI 3.1 שאפשר ליצור ממנו לקוח. בתיעוד יש דוגמאות ב-curl, ב-Node וב-Python. ה-CLI של מיומנות הסוכן הוא גם קובץ Python יחיד שאפשר לקרוא ולהפעיל מסקריפטים.

04כמה ראשים אפשר ליצור בבת אחת?

עד 30 יצירות ראש בדקה לכל חשבון, וכל אחת רצה בתור. ליותר מ-1,000 ראשים, כתבו לנו בנוגע לחשבוניות ולקיבולת.

05זה ה-API של MetaHuman של Epic?

לא. ממשקי ה-API של MetaHuman של Epic מפעילים בסקריפט את MetaHuman Creator בתוך Unreal Engine. FaceNinja יוצר את הראש מתמונות, כשירות אינטרנט, ומוסר לכם את הקבצים ואת ה-MetaHuman ZIP להכנסה ל-Unreal.

06אפשר ליצור ראש מסט תמונות?

כן, בבטא: שחזור מכמה תמונות של סשן אחד מחזיר גם את מיקום המצלמה ואת אורך המוקד של כל תמונה. כתבו לנו אם רוצים לנסות עם סט הצילום שלכם.