L’API de têtes MetaHuman, conçue pour les lots.

Envoyer. Être prévenu. Récupérer.

1. Envoyer.

   POST /v1/heads avec 1 à 15 photos d’une même personne, en fichiers multipart ou en identifiants de photos envoyées au préalable. Ajoutez un Idempotency-Key : une nouvelle tentative ne crée ni ne facture jamais une seconde tête.

2. Être prévenu.

   Choisissez comment : un webhook signé vers votre serveur, un canal d’événements envoyés par le serveur, ou un long polling ?wait=60 pour les scripts.

3. Récupérer.

   Demandez glb, fbx, obj, stl, ply ou metahuman_zip, avec ou sans blendshapes ARKit. Vous obtenez un lien signé qui ne demande aucune clé. Conservez l’identifiant de la tête, pas le lien. Ce que contient chaque format

Les crédits d’une tête en échec reviennent automatiquement, et error.code en donne la raison.

Un webhook, et votre backend a tout ce qu’il lui faut.

Créez la tête, conservez son identifiant, et agissez quand nous vous appelons. Voilà toute l’intégration, en 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);
});

Raccourci pour la lecture. La référence EN contient la requête complète, la vérification de la signature et chaque erreur.

Un casting depuis un dossier, sans risque de le lancer deux fois.

Un lot, c’est beaucoup de créations unitaires. Donnez à chacune une clé d’idempotence tirée de vos propres données, comme le nom du dossier : vous pouvez relancer tout le script après un plantage sans créer ni payer une tête deux fois. Laissez ensuite les webhooks vous dire quelles têtes sont terminées.

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

Ou laissez votre agent écrire l’intégration.

La référence de l’API, le fichier OpenAPI et llms.txt sont écrits pour les humains et pour les modèles de langage. Donnez le skill à votre agent : il peut créer des têtes directement pour vous, ou écrire et tester le script de pipeline adapté à votre stack.

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.

Conçu pour les nouvelles tentatives, les files d’attente et les mauvaises photos.

Les chiffres à prendre en compte.

La référence fait foi. Si un chiffre ici diffère, c’est la référence qui l’emporte.

Le visage d’un joueur dès le premier jour du fichier de sauvegarde.

Laissez les joueurs apporter leur propre visage, ou construisez un casting de PNJ à partir d’acteurs consentants. Chaque tête est le même maillage avec un visage différent : un seul rig, un seul matériau et un seul jeu d’animations conviennent à toutes. Les 52 blendshapes ARKit acceptent la synchro labiale ou la caméra du joueur.

GLB pour Unity, Godot et le web ; FBX et MetaHuman ZIP pour Unreal. L’automatisation Unreal est en accès anticipé : demandez-la.

Nos conditions exigent l’accord de la personne sur la photo et interdisent les photos d’enfants. Intégrez la même règle à votre parcours.

Vous utilisez déjà une autre API photo vers MetaHuman ?

Si votre intégration crée déjà une tête, l’attend et télécharge un fichier, elle garde la même forme ici. Les chemins, les noms de champs et l’étape du fichier diffèrent, et le guide de migration les met en correspondance appel par appel.

Questions de développeurs.

01Y a-t-il un bac à sable ?

Ajoutez ?dry_run à un appel de création. Il vérifie la requête et renvoie un devis sans créer de tête ni vous facturer.

02Puis-je l’appeler depuis un navigateur ou une application mobile ?

Non. Gardez la clé sur votre serveur. Les liens signés d’envoi et de téléchargement n’ont pas besoin de clé : un client peut donc envoyer ou télécharger directement.

03Quels SDK existe-t-il ?

Du HTTP simple et un fichier OpenAPI 3.1 à partir duquel générer un client. La référence propose des exemples en curl, Node et Python. La CLI du skill d’agent est aussi un unique fichier Python que vous pouvez lire et appeler depuis vos scripts.

04Combien de têtes puis-je créer à la fois ?

Jusqu’à 30 créations de tête par minute et par compte, et chacune passe par la file d’attente. Au-delà de 1 000 têtes, écrivez-nous au sujet de la facturation et de la capacité.

05S’agit-il de l’API MetaHuman d’Epic ?

Non. Les API MetaHuman d’Epic pilotent MetaHuman Creator dans Unreal Engine. FaceNinja crée la tête à partir de photos, sous forme de service web, et vous remet les fichiers et le MetaHuman ZIP à importer dans Unreal.

06Peut-il créer une tête à partir d’un ensemble de photos ?

Oui, en Beta : la reconstruction à partir de plusieurs photos d’une même session renvoie aussi la position de la caméra et la focale de chaque photo. Écrivez-nous si vous voulez l’essayer avec votre jeu de captures.