API kepala MetaHuman, dibuat untuk batch.

Kirim. Dikabari. Ambil.

1. Kirim.

   POST /v1/heads dengan 1 sampai 15 foto satu orang, sebagai file multipart atau id yang Anda unggah lebih dulu. Tambahkan Idempotency-Key, dan percobaan ulang tidak akan membuat atau menagih kepala kedua.

2. Dikabari.

   Pilih caranya: webhook bertanda tangan ke server Anda, aliran server-sent event, atau long poll ?wait=60 untuk skrip.

3. Ambil.

   Minta glb, fbx, obj, stl, ply, atau metahuman_zip, dengan atau tanpa shape ARKit. Anda mendapat tautan bertanda tangan yang tidak memerlukan kunci. Simpan id kepalanya, bukan tautannya. Isi tiap format

Kredit kepala yang gagal kembali secara otomatis, dan error.code menjelaskan penyebabnya.

Webhook adalah semua yang dibutuhkan backend Anda.

Buat kepalanya, simpan id-nya, dan bertindaklah saat kami memanggil Anda. Inilah seluruh integrasinya, dalam 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);
});

Dipersingkat agar mudah dibaca. Referensi EN memuat permintaan lengkap, pemeriksaan tanda tangan, dan setiap error.

Satu cast dari folder, aman dijalankan dua kali.

Batch adalah banyak pembuatan tunggal. Beri masing-masing kunci idempotensi yang Anda turunkan dari data Anda sendiri, seperti nama folder, dan Anda bisa menjalankan ulang seluruh skrip setelah crash tanpa membuat atau membayar sebuah kepala dua kali. Lalu biarkan webhook memberi tahu kepala mana yang sudah selesai.

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}"})

Atau minta agen Anda menulis integrasinya.

Referensi API, file OpenAPI, dan llms.txt ditulis untuk manusia dan untuk model bahasa. Beri agen Anda skill-nya dan ia bisa langsung membuat kepala untuk Anda, atau menulis dan menguji skrip pipeline untuk stack Anda.

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.

Dibuat untuk retry, antrean, dan foto yang buruk.

Angka-angka yang perlu Anda jadikan acuan desain.

Referensi adalah sumber kebenaran. Jika ada angka di sini yang berbeda, yang berlaku adalah referensi.

Wajah pemain sudah ada sejak hari pertama file simpanan.

Biarkan pemain membawa wajah mereka sendiri, atau bangun cast NPC dari aktor yang setuju. Setiap kepala adalah mesh yang sama dengan wajah berbeda, jadi satu rig, satu material, dan satu set animasi cocok untuk semuanya. 52 blendshape ARKit bisa digerakkan oleh lip sync atau kamera pemain.

GLB untuk Unity, Godot, dan web; FBX dan MetaHuman ZIP untuk Unreal. Otomatisasi Unreal tersedia dalam akses awal: minta aksesnya.

Ketentuan kami mewajibkan izin dari orang di foto dan melarang foto anak-anak. Terapkan aturan yang sama di alur Anda.

Sudah memakai API foto-ke-MetaHuman lain?

Kalau integrasi Anda sudah membuat kepala, menunggunya, dan mengunduh file, bentuknya tetap sama di sini. Path, nama field, dan langkah file berbeda, dan panduan migrasi memetakannya panggilan demi panggilan.

Pertanyaan developer.

01Apakah ada sandbox?

Tambahkan ?dry_run ke panggilan pembuatan. Ia memeriksa permintaan dan mengembalikan perkiraan biaya tanpa membuat kepala atau menagih Anda.

02Bisakah saya memanggilnya dari browser atau aplikasi seluler?

Tidak. Simpan kuncinya di server Anda. Tautan unggah dan unduh bertanda tangan tidak memerlukan kunci, jadi klien bisa mengunggah atau mengunduh langsung.

03SDK apa saja yang tersedia?

HTTP biasa dan file OpenAPI 3.1 yang bisa Anda pakai untuk membuat klien. Referensi memuat contoh curl, Node, dan Python. CLI skill agen juga berupa satu file Python yang bisa Anda baca dan panggil dari skrip.

04Berapa kepala yang bisa saya buat sekaligus?

Hingga 30 pembuatan kepala per menit per akun, dan masing-masing berjalan di antrean. Untuk lebih dari 1.000 kepala, tulis ke kami soal invoice dan kapasitas.

05Apakah ini API MetaHuman milik Epic?

Bukan. API MetaHuman milik Epic menjalankan skrip MetaHuman Creator di dalam Unreal Engine. FaceNinja membuat kepala dari foto, sebagai layanan web, dan memberi Anda file serta MetaHuman ZIP untuk dibawa ke Unreal.

06Bisakah ia membuat kepala dari sekumpulan foto?

Bisa, dalam beta: rekonstruksi dari beberapa foto dalam satu sesi juga mengembalikan posisi kamera dan panjang fokus tiap foto. Tulis ke kami kalau Anda ingin mencobanya dengan set foto Anda.