Dokumentasi API

Face Recognition · DRW App

v1.0

Face Recognition API

REST API untuk mendaftarkan wajah, mengenali wajah, dan mengelola database wajah. Dapat diintegrasikan dari server manapun menggunakan HTTP request standar.

https://face.drwapp.com multipart/form-data atau application/json

Pengantar

API ini memungkinkan server eksternal untuk:

  • Mendaftarkan wajah — simpan foto beserta nama ke database
  • Mengenali wajah — cocokkan foto dengan database, dapatkan nama + confidence score
  • Mengelola database — lihat daftar orang terdaftar, statistik, dan hapus data

API menggunakan format multipart/form-data (upload file) atau application/json (gambar Base64). Semua response dalam format JSON.

Autentikasi

Semua request dari server eksternal wajib menyertakan token di header Authorization.

Header yang wajib dikirim

Authorization: Bearer 29b2a81ff6f3c5bb8e717affe27154cf4a9a0f07d7c47807
UI face.drwapp.com — tidak perlu token, sudah diizinkan otomatis.
Server eksternal — wajib kirim header Authorization di setiap request.

Contoh penggunaan:

curl -X POST https://face.drwapp.com/api/faces/list \
  -H "Authorization: Bearer 29b2a81ff6f3c5bb8e717affe27154cf4a9a0f07d7c47807"
401 — Token tidak valid atau tidak ada
{"success": false, "error": "Unauthorized. Sertakan header: Authorization: Bearer <token>"}

Format Gambar

Cara 1: Upload File

Kirim sebagai multipart/form-data dengan field image.

Format: JPG, PNG, WEBP

Ukuran maks: 15 MB

Cara 2: Base64 JSON

Kirim sebagai Base64 di field image_base64 dengan Content-Type: application/json.

Prefix opsional: data:image/jpg;base64,...

Tips Foto Terbaik

  • • Wajah menghadap ke depan, terlihat jelas
  • • Pencahayaan cukup, hindari backlight
  • • Satu wajah per foto saat registrasi
  • • Resolusi minimal 200×200 piksel

Error Handling

Semua error dikembalikan dalam format JSON dengan success: false dan error berisi pesan.

HTTP Status Penyebab Umum
200Request berhasil
400Nama kosong, tidak ada wajah terdeteksi, lebih dari 1 wajah saat registrasi
404Database kosong, atau person_id tidak ditemukan
500Error internal pada server

Contoh response error:

{"success": false, "error": "Tidak ada wajah terdeteksi dalam foto"}

Endpoint

GET /health Health Check

Periksa apakah layanan Face Recognition API sedang berjalan.

curl https://face.drwapp.com/health
200 OK
{"status": "ok", "service": "face-api"}
POST /api/faces/register Daftarkan Wajah

Mendaftarkan wajah baru ke database. Untuk menambah foto ke orang yang sama, kirim ulang dengan person_id yang sama.

Parameter Request

multipart/form-data ATAU application/json
name string Wajib

Nama lengkap orang yang didaftarkan.

image file Wajib*

File gambar (JPG/PNG/WEBP). Gunakan ini atau image_base64.

image_base64 string Wajib*

Gambar dalam format Base64 (dengan atau tanpa prefix data:image/...;base64,).

person_id string Opsional

ID person yang sudah ada. Jika dikirim, foto ditambahkan ke orang tersebut (maks 5 foto untuk akurasi terbaik).

curl -X POST https://face.drwapp.com/api/faces/register \
  -F "name=Budi Santoso" \
  -F "image=@/path/to/foto.jpg"

# Tambah foto ke orang yang sama
curl -X POST https://face.drwapp.com/api/faces/register \
  -F "name=Budi Santoso" \
  -F "person_id=abc123def456" \
  -F "image=@/path/to/foto2.jpg"

Response

200 — Berhasil
{ "success": true, "person_id": "abc123def456", "name": "Budi Santoso", "photo_count": 1, "filename": "e3f8a1b2c4d5.jpg" }
400 — Error
{"success": false, "error": "Tidak ada wajah terdeteksi dalam foto"}
POST /api/faces/recognize Kenali Wajah

Mendeteksi dan mencocokkan semua wajah dalam foto dengan database. Mendukung foto dengan banyak wajah sekaligus.

Parameter Request

multipart/form-data ATAU application/json
image file Wajib*

File gambar (JPG/PNG/WEBP).

image_base64 string Wajib*

Gambar dalam format Base64.

tolerance float 0.3–0.7 Opsional

Toleransi kecocokan. Default: 0.5. Nilai kecil = lebih ketat, nilai besar = lebih longgar.

curl -X POST https://face.drwapp.com/api/faces/recognize \
  -F "image=@/path/to/foto.jpg" \
  -F "tolerance=0.5"

Response

200 — Berhasil
{ "success": true, "total_faces": 2, "matched": 1, "unknown": 1, "tolerance_used": 0.5, "results": [ { "matched": true, "person_id": "abc123def456", "name": "Budi Santoso", "confidence": 87.3, "distance": 0.127, "location": { "top": 50, "right": 200, "bottom": 180, "left": 80 } }, { "matched": false, "name": "Tidak Dikenal", "confidence": 31.2, "distance": 0.688, "location": { "top": 60, "right": 380, "bottom": 190, "left": 260 } } ] }
404 — Database Kosong
{"success": false, "error": "Belum ada wajah terdaftar di database"}
GET /api/faces/list Daftar Database

Mengambil semua data orang yang terdaftar di database wajah.

curl https://face.drwapp.com/api/faces/list
200 OK
{ "success": true, "total": 2, "persons": [ { "id": "abc123def456", "name": "Budi Santoso", "photo_count": 3, "created_at": "2025-05-14T10:30:00", "updated_at": "2025-05-14T11:00:00" } ] }
GET /api/faces/stats Statistik

Mengambil ringkasan statistik database (jumlah orang dan total encoding).

curl https://face.drwapp.com/api/faces/stats
200 OK
{"success": true, "total_persons": 5, "total_encodings": 12}
DELETE /api/faces/delete/{person_id} Hapus Person

Menghapus semua data (foto dan encoding) milik seorang person secara permanen.

Operasi ini tidak dapat dibatalkan. Semua foto dan encoding akan dihapus permanen.

Path Parameter

person_id string Wajib

ID unik person yang ingin dihapus (dari endpoint register atau list).

curl -X DELETE https://face.drwapp.com/api/faces/delete/abc123def456
200 — Berhasil
{"success": true, "message": "'Budi Santoso' berhasil dihapus"}
404 — Tidak Ditemukan
{"success": false, "error": "Person tidak ditemukan"}

Ringkasan Endpoint

Method Endpoint Fungsi
GET /health Cek status layanan
POST /api/faces/register Daftarkan wajah baru
POST /api/faces/recognize Kenali wajah dari foto
GET /api/faces/list Daftar semua orang di database
GET /api/faces/stats Statistik database
DELETE /api/faces/delete/{person_id} Hapus person dari database

Contoh Integrasi Lengkap

Alur lengkap: daftarkan wajah → kenali → cek database → hapus.

Python

import requests, base64

BASE = "https://face.drwapp.com"

# 1. Daftarkan wajah
with open("foto.jpg", "rb") as f:
    reg = requests.post(f"{BASE}/api/faces/register",
        data={"name": "Budi Santoso"},
        files={"image": ("foto.jpg", f, "image/jpeg")})
pid = reg.json()["person_id"]
print(f"Terdaftar: {pid}")

# 2. Kenali wajah
with open("foto_test.jpg", "rb") as f:
    rec = requests.post(f"{BASE}/api/faces/recognize",
        data={"tolerance": "0.5"},
        files={"image": ("foto_test.jpg", f, "image/jpeg")})
for face in rec.json()["results"]:
    print(f"{'Dikenal: ' + face['name'] if face['matched'] else 'Tidak dikenal'}")

# 3. Cek database
persons = requests.get(f"{BASE}/api/faces/list").json()
print(f"Total: {persons['total']} orang")

# 4. Hapus
print(requests.delete(f"{BASE}/api/faces/delete/{pid}").json()["message"])

JavaScript (Node.js)

import fs from "fs";
import FormData from "form-data";
import fetch from "node-fetch";

const BASE = "https://face.drwapp.com";

// 1. Daftarkan wajah
const form = new FormData();
form.append("name", "Budi Santoso");
form.append("image", fs.createReadStream("foto.jpg"), "foto.jpg");
const { person_id } = await fetch(`${BASE}/api/faces/register`, { method:"POST", body:form }).then(r=>r.json());

// 2. Kenali wajah
const form2 = new FormData();
form2.append("image", fs.createReadStream("foto_test.jpg"), "foto_test.jpg");
form2.append("tolerance", "0.5");
const result = await fetch(`${BASE}/api/faces/recognize`, { method:"POST", body:form2 }).then(r=>r.json());
result.results.forEach(f => console.log(f.matched ? `Dikenal: ${f.name}` : "Tidak dikenal"));

// 3. Hapus
await fetch(`${BASE}/api/faces/delete/${person_id}`, { method:"DELETE" });

PHP

<?php
define('BASE', 'https://face.drwapp.com');

// 1. Daftarkan wajah
$ch = curl_init(BASE . '/api/faces/register');
curl_setopt_array($ch, [CURLOPT_POST=>true, CURLOPT_RETURNTRANSFER=>true,
    CURLOPT_POSTFIELDS=>['name'=>'Budi Santoso','image'=>new CURLFile('/path/foto.jpg','image/jpeg')]]);
$reg = json_decode(curl_exec($ch), true); curl_close($ch);
$pid = $reg['person_id'];

// 2. Kenali wajah
$ch = curl_init(BASE . '/api/faces/recognize');
curl_setopt_array($ch, [CURLOPT_POST=>true, CURLOPT_RETURNTRANSFER=>true,
    CURLOPT_POSTFIELDS=>['tolerance'=>'0.5','image'=>new CURLFile('/path/foto_test.jpg','image/jpeg')]]);
$rec = json_decode(curl_exec($ch), true); curl_close($ch);
foreach ($rec['results'] as $face) echo $face['matched'] ? "Dikenal: {$face['name']}\n" : "Tidak dikenal\n";

// 3. Hapus
$ch = curl_init(BASE . "/api/faces/delete/{$pid}");
curl_setopt_array($ch, [CURLOPT_CUSTOMREQUEST=>'DELETE', CURLOPT_RETURNTRANSFER=>true]);
$del = json_decode(curl_exec($ch), true); curl_close($ch);
echo $del['message'];
?>
Face Recognition API · DRW App · Kembali ke Aplikasi