A API de cabeças MetaHuman, feita para lotes.

Envie. Receba o aviso. Busque.

1. Envie.

   POST /v1/heads com 1 a 15 fotos de uma pessoa, como arquivos multipart ou ids que você enviou antes. Adicione um Idempotency-Key, e uma nova tentativa nunca cria nem cobra uma segunda cabeça.

2. Receba o aviso.

   Escolha como: um webhook assinado para o seu servidor, um fluxo de server-sent events ou um long poll com ?wait=60 para scripts.

3. Busque.

   Peça glb, fbx, obj, stl, ply ou metahuman_zip, com ou sem blendshapes ARKit. Você recebe um link assinado que não precisa de chave. Guarde o id da cabeça, não o link. O que cada formato contém

Os créditos de uma cabeça que falha voltam automaticamente, e error.code diz o motivo.

Um webhook é tudo o que o seu backend precisa.

Crie a cabeça, guarde o id e aja quando ligarmos para você. Esta é a integração inteira, em 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);
});

Encurtado para leitura. A referência EN traz a requisição completa, a verificação da assinatura e todos os erros.

Um elenco a partir de uma pasta, seguro para rodar duas vezes.

Um lote são muitas criações individuais. Dê a cada uma uma chave de idempotência derivada dos seus próprios dados, como o nome da pasta, e você pode rodar o script inteiro de novo depois de uma falha sem criar nem pagar uma cabeça duas vezes. Depois, deixe os webhooks dizerem quais cabeças estão prontas.

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 deixe o seu agente escrever a integração.

A referência da API, o arquivo OpenAPI e o llms.txt são escritos para pessoas e para modelos de linguagem. Dê a skill ao seu agente e ele pode criar cabeças para você diretamente, ou escrever e testar o script de pipeline para a sua 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.

Feita para novas tentativas, filas e fotos ruins.

Os números para planejar o projeto.

A referência é a fonte da verdade. Se um número aqui divergir, vale a referência.

O rosto de um jogador desde o primeiro dia do save.

Deixe os jogadores trazerem o próprio rosto, ou monte um elenco de NPCs com atores que consentiram. Toda cabeça é a mesma malha com um rosto diferente, então um rig, um material e um conjunto de animações servem para todas. Os 52 blendshapes ARKit aceitam lip sync ou a câmera do jogador.

GLB para Unity, Godot e a web; FBX e o MetaHuman ZIP para Unreal. A automação para Unreal está em acesso antecipado: peça acesso.

Nossos termos exigem a permissão da pessoa na foto e proíbem fotos de crianças. Incorpore a mesma regra ao seu fluxo.

Já usa outra API de foto para MetaHuman?

Se a sua integração já cria uma cabeça, espera por ela e baixa um arquivo, ela mantém o mesmo formato aqui. Os caminhos, os nomes de campo e a etapa do arquivo mudam, e o guia de migração os mapeia chamada por chamada.

Perguntas de desenvolvedores.

01Existe um sandbox?

Adicione ?dry_run a uma chamada de criação. Ele verifica a requisição e devolve uma cotação sem criar uma cabeça nem cobrar você.

02Posso chamar a API de um navegador ou de um app mobile?

Não. Mantenha a chave no seu servidor. Os links assinados de envio e de download não precisam de chave, então um cliente pode enviar ou baixar diretamente.

03Quais SDKs existem?

HTTP puro e um arquivo OpenAPI 3.1 a partir do qual você pode gerar um cliente. A referência traz exemplos em curl, Node e Python. A CLI da skill de agente também é um único arquivo Python que você pode ler e chamar de scripts.

04Quantas cabeças posso criar ao mesmo tempo?

Até 30 criações de cabeça por minuto, por conta, e cada uma roda na fila. Para mais de 1.000 cabeças, escreva para nós sobre faturamento e capacidade.

05Esta é a API MetaHuman da Epic?

Não. As APIs MetaHuman da Epic automatizam por script o MetaHuman Creator dentro do Unreal Engine. O FaceNinja cria a cabeça a partir de fotos, como um serviço web, e entrega os arquivos e o MetaHuman ZIP para você levar ao Unreal.

06Ele consegue criar uma cabeça a partir de um conjunto de fotos?

Sim, em beta: a reconstrução a partir de várias fotos de uma mesma sessão também devolve a posição da câmera e a distância focal de cada foto. Escreva para nós se quiser testar com o seu conjunto de captura.