API голов MetaHuman, рассчитанный на пакетную обработку.

Отправьте. Дождитесь ответа. Заберите.

1. Отправьте.

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

2. Дождитесь ответа.

   Выберите способ: подписанный webhook на ваш сервер, поток server-sent events или long poll ?wait=60 для скриптов.

3. Заберите.

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

Кредиты за неудачную голову возвращаются автоматически, а error.code объясняет причину.

Вашему бэкенду нужен только webhook.

Создайте голову, сохраните её id и действуйте, когда мы обратимся к вашему 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 есть полный запрос, проверка подписи и все ошибки.

Группа людей из папки; безопасно запускать дважды.

Пакетный запуск — это много одиночных созданий. Дайте каждому ключ идемпотентности, который вы выводите из своих данных, например из имени папки, и весь скрипт можно перезапустить после сбоя, не создавая и не оплачивая голову дважды. А о готовых головах вам сообщат webhook.

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Можно ли вызывать API из браузера или мобильного приложения?

Нет. Храните ключ на сервере. Подписанным ссылкам для загрузки и скачивания ключ не нужен, поэтому клиент может загружать и скачивать напрямую.

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Можно ли сделать голову по набору фото?

Да, в бете: реконструкция по нескольким фото одной съёмки также возвращает положение камеры и фокусное расстояние для каждого фото. Напишите нам, если хотите попробовать на своём наборе кадров.