배치를 위해 만든 MetaHuman 헤드 API.

보내기. 알림 받기. 가져오기.

1. 보내기.

   한 사람의 사진 1~15장을 멀티파트 파일이나 미리 업로드한 id로 POST /v1/heads에 보냅니다. Idempotency-Key를 붙이면 재시도해도 두 번째 헤드를 만들거나 청구하지 않습니다.

2. 알림 받기.

   방식을 고르십시오. 서버로 오는 서명된 webhook, 서버 전송 이벤트(SSE) 스트림, 또는 스크립트용 ?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);
});

읽기 쉽게 줄였습니다. 전체 요청, 서명 검증, 모든 오류는 레퍼런스에 있습니다: API 레퍼런스 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 캐스트를 만드십시오. 모든 헤드는 얼굴만 다른 같은 메시이므로 리그 하나, 머티리얼 하나, 애니메이션 세트 하나가 모두에 맞습니다. ARKit 블렌드셰이프 52개로 립싱크나 플레이어 카메라 입력을 받을 수 있습니다.

Unity, Godot, 웹에는 GLB, Unreal에는 FBX와 MetaHuman ZIP. Unreal 자동화는 얼리 액세스입니다. 요청하기.

약관상 사진 속 인물의 허락이 필요하며 아동 사진은 금지됩니다. 같은 규칙을 플로우에 넣으십시오.

이미 다른 사진→MetaHuman API를 쓰고 있습니까?

연동 코드가 이미 헤드를 만들고, 기다리고, 파일을 다운로드한다면 그 구조는 여기서도 그대로입니다. 경로, 필드 이름, 파일 단계가 다르며, 마이그레이션 가이드가 호출 하나하나를 대응시켜 줍니다.

개발자 질문.

01샌드박스가 있습니까?

생성 호출에 ?dry_run을 붙이십시오. 요청을 검사하고, 헤드를 만들거나 청구하지 않은 채 견적을 반환합니다.

02브라우저나 모바일 앱에서 호출할 수 있습니까?

아닙니다. 키는 서버에 두십시오. 서명된 업로드·다운로드 링크는 키가 필요 없으므로 클라이언트가 직접 업로드하거나 다운로드할 수 있습니다.

03어떤 SDK가 있습니까?

일반 HTTP와, 클라이언트를 생성할 수 있는 OpenAPI 3.1 파일이 있습니다. 레퍼런스에는 curl, Node, Python 예제가 있습니다. 에이전트 스킬의 CLI도 Python 파일 하나라서 읽어 보고 스크립트에서 호출할 수 있습니다.

04한 번에 헤드를 몇 개 만들 수 있습니까?

계정당 분당 헤드 생성 최대 30건이며, 각각 대기열에서 처리됩니다. 헤드가 1,000개를 넘는다면 청구서 발행과 처리 용량에 대해 문의해 주십시오.

05Epic의 MetaHuman API입니까?

아닙니다. Epic의 MetaHuman API는 Unreal Engine 안에서 MetaHuman Creator를 스크립트로 다룹니다. FaceNinja는 웹 서비스로 사진에서 헤드를 만들고, Unreal로 가져갈 파일과 MetaHuman ZIP을 건네 드립니다.

06사진 세트로 헤드를 만들 수 있습니까?

네, 베타입니다. 한 세션에서 찍은 여러 장의 사진으로 재구성하며, 사진마다 카메라 위치와 초점 거리도 함께 돌려줍니다. 보유한 촬영 세트로 시험해 보고 싶다면 문의해 주십시오.