API رؤوس MetaHuman، مصمَّم للدفعات.

إرسال. إشعار. جلب.

1. إرسال.

   POST /v1/heads مع صورة واحدة إلى 15 صورة لشخص واحد، كملفات multipart أو كمعرّفات صور رُفعت مسبقًا. ومع إضافة Idempotency-Key، لا تصنع إعادة المحاولة رأسًا ثانيًا ولا تحتسبه أبدًا.

2. إشعار.

   بالطريقة التي تختارها: webhook موقّع إلى خادمك، أو تدفق أحداث يرسلها الخادم، أو استطلاع طويل ?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 من ممثلين موافقين. كل رأس هو الشبكة نفسها بوجه مختلف، فيناسبها جميعًا rig واحد ومادة واحدة ومجموعة حركات واحدة. وتستقبل أشكال ARKit الـ52 مزامنة الشفاه أو كاميرا اللاعب.

GLB لـ Unity وGodot والويب؛ وFBX وMetaHuman ZIP لـ Unreal. وأتمتة Unreal متاحة في الوصول المبكر: طلب الوصول.

تشترط شروطنا إذن الشخص الذي في الصورة، وتمنع صور الأطفال. ويُرجى بناء القاعدة نفسها في مسار منتجك.

الانتقال من API آخر لتحويل الصور إلى MetaHuman؟

إذا كان تكاملك ينشئ رأسًا وينتظره وينزّل ملفًا، فسيحتفظ ببنيته هنا. تختلف المسارات وأسماء الحقول وخطوة الملفات، ويطابقها دليل الانتقال استدعاءً باستدعاء.

أسئلة المطوّرين.

01هل توجد بيئة تجريبية (sandbox)؟

يكفي إضافة ?dry_run إلى استدعاء الإنشاء. يفحص الطلب ويُعيد عرض سعر دون صنع رأس أو احتساب أي مبلغ.

02هل يمكن استدعاؤه من متصفح أو تطبيق جوال؟

لا. يبقى المفتاح على خادمك. وروابط الرفع والتنزيل الموقّعة لا تحتاج إلى مفتاح، فيستطيع العميل الرفع أو التنزيل مباشرة.

03ما حزم SDK المتاحة؟

HTTP عادي وملف OpenAPI 3.1 يمكن توليد عميل منه. وفي المرجع أمثلة بـ curl وNode وPython. وأداة سطر الأوامر الخاصة بمهارة الوكيل ملف Python واحد أيضًا، يمكن قراءته واستدعاؤه من السكربتات.

04كم رأسًا يمكنني صنعه دفعة واحدة؟

حتى 30 عملية إنشاء رأس في الدقيقة لكل حساب، ويمر كلٌّ منها في الطابور. ولأكثر من 1,000 رأس، يُرجى الكتابة إلينا بشأن الفوترة والسعة.

05هل هذه واجهة MetaHuman API من Epic؟

لا. واجهات MetaHuman البرمجية من Epic تتحكم في MetaHuman Creator بالسكربتات داخل Unreal Engine. أما FaceNinja فخدمة ويب تصنع الرأس من الصور، وتسلّمك الملفات وMetaHuman ZIP لنقلها إلى Unreal.

06هل يمكنه بناء رأس من مجموعة صور؟

نعم، في مرحلة Beta: إعادة البناء من عدة صور من جلسة واحدة تعيد أيضًا موضع الكاميرا والبعد البؤري لكل صورة. يُرجى الكتابة إلينا لتجربتها مع مجموعة صورك الملتقطة.