La API de cabezas MetaHuman, pensada para lotes.

Envía. Recibe aviso. Descarga.

1. Envía.

   POST /v1/heads con 1 a 15 fotos de una misma persona, como archivos multipart o ids que subiste antes. Añade un Idempotency-Key y un reintento nunca crea ni cobra una segunda cabeza.

2. Recibe aviso.

   Elige cómo: un webhook firmado a tu servidor, un flujo de eventos enviados por el servidor, o un long poll con ?wait=60 para scripts.

3. Descarga.

   Pide glb, fbx, obj, stl, ply o metahuman_zip, con o sin blendshapes ARKit. Recibes un enlace firmado que no necesita clave. Guarda el id de la cabeza, no el enlace. Qué contiene cada formato

Los créditos de una cabeza fallida vuelven automáticamente, y error.code dice por qué.

Un webhook es todo lo que tu backend necesita.

Crea la cabeza, guarda su id y actúa cuando te llamemos. Esta es toda la integración, 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);
});

Acortado para leerlo mejor. La referencia EN tiene la solicitud completa, la comprobación de la firma y todos los errores.

Un reparto desde una carpeta, seguro de ejecutar dos veces.

Un lote son muchas creaciones sueltas. Dale a cada una una clave de idempotencia que derives de tus propios datos, como el nombre de la carpeta, y podrás volver a ejecutar todo el script tras un fallo sin crear ni pagar una cabeza dos veces. Después deja que los webhooks te digan qué cabezas están listas.

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

O deja que tu agente escriba la integración.

La referencia de la API, el archivo OpenAPI y llms.txt están escritos para personas y para modelos de lenguaje. Dale la skill a tu agente y podrá crear cabezas por ti directamente, o escribir y probar el script de pipeline para tu 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.

Pensada para reintentos, colas y malas fotos.

Los números que debes tener en cuenta al diseñar.

La referencia es la fuente de verdad. Si un número de aquí difiere, manda la referencia.

La cara de un jugador desde el día uno de su partida guardada.

Deja que los jugadores traigan su propia cara, o crea un reparto de NPC a partir de actores que han dado su consentimiento. Cada cabeza es la misma malla con otra cara, así que un rig, un material y un conjunto de animaciones sirven para todas. Los 52 blendshapes ARKit admiten lip sync o la cámara del jugador.

GLB para Unity, Godot y la web; FBX y el MetaHuman ZIP para Unreal. La automatización de Unreal está en acceso anticipado: pídela.

Nuestros términos exigen el permiso de la persona de la foto y prohíben las fotos de niños. Incluye la misma regla en tu flujo.

¿Ya usas otra API de foto a MetaHuman?

Si tu integración ya crea una cabeza, espera y descarga un archivo, aquí conserva su forma. Las rutas, los nombres de campo y el paso del archivo cambian, y la guía de migración los equipara llamada por llamada.

Preguntas de desarrolladores.

01¿Hay un sandbox?

Añade ?dry_run a una llamada de creación. Comprueba la solicitud y devuelve un presupuesto sin crear una cabeza ni cobrarte.

02¿Puedo llamarla desde un navegador o una app móvil?

No. Guarda la clave en tu servidor. Los enlaces firmados de subida y descarga no necesitan clave, así que un cliente puede subir o descargar directamente.

03¿Qué SDK hay?

HTTP puro y un archivo OpenAPI 3.1 a partir del cual puedes generar un cliente. La referencia tiene ejemplos con curl, Node y Python. La CLI de la skill para agentes también es un único archivo de Python que puedes leer y llamar desde scripts.

04¿Cuántas cabezas puedo crear a la vez?

Hasta 30 creaciones por minuto en cada cuenta, y cada cabeza se ejecuta en la cola. Para más de 1000 cabezas, escríbenos para hablar de facturación y capacidad.

05¿Es la API de MetaHuman de Epic?

No. Las API de MetaHuman de Epic automatizan MetaHuman Creator dentro de Unreal Engine. FaceNinja crea la cabeza a partir de fotos, como servicio web, y te entrega los archivos y el MetaHuman ZIP para llevar a Unreal.

06¿Puede crear una cabeza a partir de un conjunto de fotos?

Sí, en beta: la reconstrucción a partir de varias fotos de una sesión también devuelve la posición de cámara y la distancia focal de cada foto. Escríbenos si quieres probarlo con tu conjunto de capturas.