面向批量处理的 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。每个头部都是同一个网格配不同的脸，所以一套绑定、一套材质和一套动画就适用于所有头部。52 个 ARKit 混合变形可以接口型同步，也可以接玩家的摄像头。

GLB 用于 Unity、Godot 和网页；FBX 和 MetaHuman ZIP 用于 Unreal。Unreal 自动化处于抢先体验阶段：申请使用。

我们的条款要求照片中的人许可，并禁止使用儿童照片。请把同样的规则写进你自己的流程里。

已经在用别的照片转 MetaHuman 的 API？

如果你的集成已经在创建头部、等待并下载文件，那么它在这里保持同样的结构。路径、字段名和文件步骤有所不同，迁移指南会逐个调用地对应起来。

开发者常见问题。

01有沙盒吗？

在创建调用上加 ?dry_run。它会检查请求并返回报价，不会生成头部，也不会扣你的费。

02能从浏览器或移动应用里调用吗？

不能。请把密钥放在你的服务器上。签名的上传和下载链接不需要密钥，所以客户端可以直接上传或下载。

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：用同一次拍摄的多张照片重建，还会返回每张照片的相机位置和焦距。如果你想用自己的拍摄素材试用，给我们写信。