API đầu MetaHuman, xây cho xử lý theo lô.

Gửi. Nhận phản hồi. Tải về.

1. Gửi.

   POST /v1/heads kèm 1 đến 15 ảnh của một người, dưới dạng tệp multipart hoặc id của ảnh bạn đã tải lên trước. Thêm một Idempotency-Key, và việc gửi lại sẽ không bao giờ tạo hay tính phí thêm một đầu 3D.

2. Nhận phản hồi.

   Bạn chọn cách nhận: webhook có chữ ký gửi tới máy chủ của bạn, một luồng server-sent event, hoặc long poll ?wait=60 cho script.

3. Tải về.

   Yêu cầu glb, fbx, obj, stl, ply hoặc metahuman_zip, có hoặc không có blendshape ARKit. Bạn nhận một liên kết có chữ ký, không cần key. Hãy lưu id của đầu 3D, đừng lưu liên kết. Mỗi định dạng chứa gì

Credit của một đầu 3D bị lỗi tự động quay lại, và error.code cho biết lý do.

Một webhook là tất cả những gì backend của bạn cần.

Tạo đầu 3D, lưu id của nó, rồi xử lý khi chúng tôi gọi bạn. Đây là toàn bộ phần tích hợp, bằng 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);
});

Đã rút gọn cho dễ đọc. Tài liệu tham chiếu EN có đủ request, bước kiểm tra chữ ký và mọi lỗi.

Một dàn nhân vật từ một thư mục, chạy hai lần vẫn an toàn.

Một lô là nhiều lệnh tạo riêng lẻ. Đặt cho mỗi lệnh một idempotency key lấy từ dữ liệu của chính bạn, như tên thư mục, và bạn có thể chạy lại toàn bộ script sau khi bị sập mà không tạo hay trả tiền cho một đầu 3D hai lần. Sau đó để các webhook cho bạn biết đầu 3D nào đã xong.

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

Hoặc để agent viết phần tích hợp.

Tài liệu tham chiếu API, tệp OpenAPI và llms.txt được viết cho cả con người và mô hình ngôn ngữ. Đưa skill cho agent, nó có thể tạo đầu 3D thẳng cho bạn, hoặc viết và kiểm thử script pipeline cho stack của bạn.

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.

Xây cho việc gửi lại, hàng đợi và ảnh xấu.

Những con số để thiết kế xung quanh.

Tài liệu tham chiếu là nguồn đáng tin cậy nhất. Nếu một con số ở đây khác, hãy theo tài liệu tham chiếu.

Khuôn mặt người chơi ngay từ ngày đầu của file lưu.

Cho người chơi mang khuôn mặt của chính họ vào game, hoặc dựng một dàn NPC từ các diễn viên đã đồng ý. Mọi đầu 3D là cùng một mesh với khuôn mặt khác nhau, nên một rig, một material và một bộ animation dùng được cho tất cả. 52 blendshape ARKit nhận lip sync hoặc camera của người chơi.

GLB cho Unity, Godot và web; FBX và MetaHuman ZIP cho Unreal. Tự động hóa Unreal đang ở giai đoạn truy cập sớm: hãy hỏi chúng tôi.

Điều khoản của chúng tôi yêu cầu có sự cho phép của người trong ảnh và cấm ảnh trẻ em. Hãy đưa cùng quy tắc đó vào luồng của bạn.

Đang dùng một API từ ảnh sang MetaHuman khác?

Nếu phần tích hợp của bạn đã tạo một đầu 3D, chờ nó rồi tải một tệp về, thì nó giữ nguyên hình dạng đó ở đây. Đường dẫn, tên trường và bước lấy tệp khác nhau, và hướng dẫn chuyển đổi ánh xạ chúng từng lệnh gọi một.

Câu hỏi của developer.

01Có sandbox không?

Thêm ?dry_run vào một lệnh tạo. Nó kiểm tra request và trả về báo giá mà không tạo đầu 3D hay tính phí bạn.

02Tôi có thể gọi từ trình duyệt hay ứng dụng di động không?

Không. Hãy giữ key trên máy chủ của bạn. Các liên kết tải lên và tải xuống có chữ ký không cần key, nên client có thể tải lên hoặc tải xuống trực tiếp.

03Có những SDK nào?

HTTP thuần và một tệp OpenAPI 3.1 để bạn tạo client. Tài liệu tham chiếu có ví dụ curl, Node và Python. CLI của skill agent cũng chỉ là một tệp Python mà bạn đọc được và gọi từ script.

04Tôi tạo được bao nhiêu đầu 3D cùng lúc?

Tối đa 30 lượt tạo đầu 3D mỗi phút cho mỗi tài khoản, và mỗi lượt chạy trong hàng đợi. Với hơn 1.000 đầu 3D, hãy nhắn cho chúng tôi về xuất hóa đơn và công suất.

05Đây có phải API MetaHuman của Epic không?

Không. API MetaHuman của Epic điều khiển MetaHuman Creator bằng script bên trong Unreal Engine. FaceNinja tạo đầu 3D từ ảnh, dưới dạng một dịch vụ web, và đưa bạn các tệp cùng MetaHuman ZIP để mang vào Unreal.

06Có thể dựng đầu 3D từ một bộ ảnh không?

Có, ở bản Beta: dựng lại từ nhiều ảnh trong cùng một buổi chụp cũng trả về vị trí camera và tiêu cự của từng ảnh. Nhắn cho chúng tôi nếu bạn muốn thử với bộ ảnh chụp của mình.