バッチのために作った、MetaHumanヘッドAPI。

送る。通知を受ける。取得する。

1. 送る。

   同一人物の写真1枚から15枚を付けて、POST /v1/headsを呼びます。写真は、multipartのファイルでも、先にアップロードしたIDでも指定できます。Idempotency-Keyを付けておけば、リトライしても2つ目のヘッドは作られず、課金もされません。

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

フォルダからキャスト一式。2回実行しても安全です。

バッチは、単発の作成をたくさん並べたものです。それぞれに、フォルダ名など自分のデータから決めた冪等性キーを付けておけば、クラッシュ後にスクリプト全体を再実行しても、同じヘッドを2回作ることも、2回分払うこともありません。どのヘッドが終わったかは、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のキャストを作れます。どのヘッドも、顔だけが違う同じメッシュなので、1つのリグ、1つのマテリアル、1セットのアニメーションが、すべてに合います。ARKitブレンドシェイプ52種は、リップシンクにも、プレイヤーのカメラにも使えます。

UnityやGodot、WebにはGLB、UnrealにはFBXとMetaHuman ZIP。Unrealの自動化はアーリーアクセスです。利用を申し込む

利用規約では、写真に写っている本人の許可を必須とし、子どもの写真を禁止しています。同じルールを、あなたのフローにも組み込んでください。

すでに別の、写真からMetaHumanを作るAPIを使っていますか？

すでに、ヘッドを作り、完了を待ち、ファイルをダウンロードする連携があるなら、ここでも同じ流れのまま使えます。パス、フィールド名、ファイルの手順は違うので、移行ガイドで呼び出しごとに対応づけています。

開発者からの質問。

01サンドボックスはありますか？

作成の呼び出しに?dry_runを付けてください。ヘッドを作らず、課金もせずに、リクエストを検査して見積もりを返します。

02ブラウザやモバイルアプリから呼び出せますか？

いいえ。キーはサーバーに置いてください。署名つきのアップロードリンクとダウンロードリンクにはキーが要らないので、クライアントが直接アップロードやダウンロードをできます。

03SDKはありますか？

素のHTTPと、クライアントを生成できるOpenAPI 3.1ファイルがあります。リファレンスには、curl、Node、Pythonの例があります。エージェント用スキルのCLIも、1つのPythonファイルで、読むことも、スクリプトから呼ぶこともできます。

04同時にいくつのヘッドを作れますか？

アカウントごとに1分あたり最大30ヘッドの作成で、それぞれキューで処理されます。1,000ヘッドを超える場合は、請求書払いや処理能力についてご連絡ください。

05これはEpicのMetaHuman APIですか？

いいえ。EpicのMetaHuman APIは、Unreal Engineの中でMetaHuman Creatorをスクリプトで操作するものです。FaceNinjaは、Webサービスとして写真からヘッドを作り、Unrealに持ち込むためのファイルとMetaHuman ZIPを渡します。

06写真のセットからヘッドを作れますか？

はい、Betaで提供しています。1回の撮影セッションの複数の写真からの再構成は、各写真のカメラ位置と焦点距離も返します。お持ちの撮影セットで試したい場合は、ご連絡ください。