1:N Search API
Endpoint untuk identifikasi wajah dari keyspace, pencarian by embedding, dan ekstraksi embedding.
← Konsep 1:N Search
Pahami top-k, candidateCount, threshold, dan alur recognition sebelum mengintegrasikan API.
Panduan Developer
Autentikasi, error handling, dan referensi sistem API FREMIS-N.
Mengenali Wajah dari Foto (1:N)
Mengirimkan satu gambar dan mencari wajah yang paling cocok di seluruh database keyspace yang ditentukan. Gunakan endpoint ini untuk skenario identifikasi — ketika identitas orang dalam foto belum diketahui. Jumlah kandidat yang dikembalikan dapat diatur melalui parameter candidateCount di dalam additional_params.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
text/plain
application/json
text/plain
curl -X POST "https://fremis-n.example.com/v1/face/recognition" \ -H "Content-Type: application/json" \ -d '{ "image": "<base64-encoded-image>", "keyspace": "karyawan-jakarta", "additional_params": { "candidateCount": 3 } }'{ "result": { "face_recognition": { "candidates": [ { "face_id": "budi-001", "similarity": 0.94, "variation": "0" }, { "face_id": "budi-002", "similarity": 0.87, "variation": "1" }, { "face_id": "siti-003", "similarity": 0.71, "variation": "0" } ] }, "face_detected": [ { "top": 0.12, "left": 0.23, "height": 0.35, "width": 0.28 } ] }}{ "code": "400", "message": "invalid arguments", "description": "failed to decode base64 image"}{ "code": "401", "message": "Inactive analytic"}"Too many requests"{ "code": "500", "message": "internal server error"}"License has not been initialized"Mengenali Wajah dari Embedding
Melakukan pencarian 1:N menggunakan vektor embedding yang sudah dihitung sebelumnya, bukan dari gambar mentah. Cocok untuk batch processing — embedding dapat diekstrak terlebih dahulu lalu digunakan ulang, menghemat waktu komputasi ekstraksi fitur. Vektor harus berupa array float yang diperoleh dari /v1/face/extract-embedding.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
text/plain
application/json
text/plain
curl -X POST "https://fremis-n.example.com/v1/face/recognition-by-embedding" \ -H "Content-Type: application/json" \ -d '{ "vector": [ 0.034, -0.12, 0.078, 0.051 ], "keyspace": "vip-customers", "additional_params": { "candidateCount": 1 } }'{ "result": { "face_recognition": { "candidates": [ { "face_id": "siti-002", "similarity": 0.96, "variation": "0" } ] } }, "message": null}{ "code": "400", "message": "invalid arguments", "description": "vector dimension mismatch: expected 512, got 3"}{ "code": "401", "message": "Inactive analytic"}"Too many requests"{ "code": "500", "message": "internal server error"}"License has not been initialized"Mengekstrak Embedding Wajah dari Foto
Mengekstrak vektor embedding dari semua wajah yang terdeteksi dalam satu gambar. Hasilnya dapat disimpan dan digunakan kembali pada endpoint /v1/face/recognition-by-embedding atau /v2/face/match untuk menghindari komputasi ulang. Respons menyertakan dua versi embedding: embeddings (hasil kuantisasi, lebih kompak) dan original (presisi penuh, tersedia jika dikonfigurasi).
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Data gambar yang di-encode dalam format base64. Semua wajah yang terdeteksi dalam gambar akan diekstrak embedding-nya.
Response Body
application/json
application/json
text/plain
application/json
text/plain
curl -X POST "https://fremis-n.example.com/v1/face/extract-embedding" \ -H "Content-Type: application/json" \ -d '{ "image": "<base64-encoded-image>" }'{ "embeddings": [ [ 0.034, -0.12, 0.078, 0.051 ] ], "detected": [ { "top": 0.12, "left": 0.23, "height": 0.35, "width": 0.28 } ], "original": [ [ 0.034112, -0.120455, 0.078231, 0.051789 ] ]}{ "code": "400", "message": "invalid arguments", "description": "no face detected in the provided image"}"Too many requests"{ "code": "500", "message": "internal server error"}"License has not been initialized"