API голів MetaHuman, створений для партій.

Надіслати. Дочекатися. Забрати.

1. Надіслати.

   POST /v1/heads із 1–15 фото однієї людини, як multipart-файли або id, які ви завантажили раніше. Додайте Idempotency-Key, і повторний запит ніколи не створить і не оплатить другу голову.

2. Дочекатися.

   Оберіть спосіб: підписаний webhook на ваш сервер, потік server-sent events або довге опитування ?wait=60 для скриптів.

3. Забрати.

   Запитайте glb, fbx, obj, stl, ply або metahuman_zip, з формами ARKit або без них. Ви отримаєте підписане посилання, якому ключ не потрібен. Зберігайте id голови, а не посилання. Що містить кожен формат

Кредити за невдалу голову повертаються автоматично, а error.code пояснює причину.

Вашому бекенду потрібен лише webhook.

Створіть голову, збережіть її id і дійте, коли ми зателефонуємо вам. Це вся інтеграція, на 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 є повний запит, перевірка підпису й усі помилки.

Акторський склад із папки, який безпечно запускати двічі.

Партія — це багато окремих створень. Дайте кожному ключ ідемпотентності, виведений зі своїх даних, наприклад з назви папки, і ви зможете перезапустити весь скрипт після збою, не створюючи й не оплачуючи голову двічі. А далі нехай 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Чи є пісочниця?

Додайте ?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Чи можна створити голову з набору фото?

Так, у бета-версії: реконструкція з кількох фото однієї сесії також повертає положення камери та фокусну відстань кожного фото. Напишіть нам, якщо хочете спробувати на своєму наборі знімків.