為批次作業而生的 MetaHuman 頭部 API。

送出。等通知。取檔。

1. 送出。

   POST /v1/heads，附上同一個人的 1 到 15 張照片，可用 multipart 檔案，或你事先上傳的 id。加上 Idempotency-Key，重試時就不會多做一個頭部，也不會多收一次費用。

2. 等通知。

   由你選擇方式：發到你伺服器的簽章 webhook、伺服器傳送事件串流，或給腳本用的 ?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);
});

為方便閱讀而縮短。完整的請求、簽章驗證和每一種錯誤，請見參考文件 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 角色。每個頭部都是同一個網格配上不同的臉，所以一套 rig、一種材質和一組動畫就適用所有頭部。52 個 ARKit 混合變形可以接口型同步，也可以接玩家的攝影機。

GLB 給 Unity、Godot 和網頁；FBX 與 MetaHuman ZIP 給 Unreal。Unreal 自動化為搶先體驗：來信詢問。

我們的條款要求取得照片中人物的許可，並禁止使用兒童的照片。請在你的流程中內建同樣的規則。

已經在用其他的照片轉 MetaHuman API？

如果你的整合已經會建立頭部、等待它完成並下載檔案，那麼來到這裡，整合的架構不變。路徑、欄位名稱和檔案步驟不同，遷移指南會逐個呼叫對照。

開發者常見問題。

01有沙箱嗎？

在建立呼叫加上 ?dry_run。它會檢查請求並回傳報價，不會做出頭部，也不會向你收費。

02可以從瀏覽器或行動 app 呼叫嗎？

不行。請把金鑰留在你的伺服器上。簽章的上傳和下載連結不需要金鑰，所以用戶端可以直接上傳或下載。

03有哪些 SDK？

純 HTTP，以及一份可用來產生用戶端程式的 OpenAPI 3.1 檔案。參考文件有 curl、Node 和 Python 範例。代理技能的 CLI 也是單一的 Python 檔案，你可以閱讀它，也可以從腳本呼叫它。

04一次可以做多少個頭部？

每個帳號每分鐘最多建立 30 個頭部，每個都在佇列中執行。如果要超過 1,000 個頭部，請寫信給我們，洽談開立發票與容量。

05這是 Epic 的 MetaHuman API 嗎？

不是。Epic 的 MetaHuman API 是在 Unreal Engine 內用腳本操作 MetaHuman Creator。FaceNinja 則是以網路服務的形式，用照片做出頭部，並把檔案和 MetaHuman ZIP 交給你，讓你帶進 Unreal。

06可以用一組照片建立頭部嗎？

可以，目前為 Beta：用同一次拍攝的多張照片重建時，也會回傳每張照片的相機位置和焦距。如果你想用你的拍攝照片組試試，請寫信給我們。