> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Pencocokan Wajah 1:1: API Face Match > Pencocokan wajah 1:1 Didit via POST /v3/face-match/ untuk verifikasi identitas dan kontrol akses. Di bawah 2 detik, bayar per penggunaan. ## OpenAPI ````yaml id/openapi-25.json POST /v3/face-match/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API Verifikasi Identitas. Lakukan autentikasi dengan header x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/face-match/: post: tags: - Standalone APIs summary: Pencocokan Wajah description: >- Bandingkan dua gambar wajah (1:1) dan dapatkan `score` kemiripan (0–100) serta `status` `Approved`/`Declined`. **Cara kerjanya.** Kedua gambar didekodekan dan dianalisis oleh model biometrik (atur `rotate_image=true` jika pengambilan gambar mungkin miring atau terbalik), lalu skor kemiripan antara kedua wajah dihitung. Skor yang **benar-benar di atas** `face_match_score_decline_threshold` (default `30`) mengembalikan `status: "Approved"`; skor yang sama dengan atau di bawahnya mengembalikan `Declined` dengan peringatan `LOW_FACE_MATCH_SIMILARITY`. Jika tidak ada pasangan wajah yang dapat dinilai sama sekali, panggilan tetap mengembalikan `200` dengan `status: "Declined"` dan peringatan `NO_REFERENCE_IMAGE` — `score` bernilai `null` pada jalur penyimpanan default, atau `0` dengan `save_api_request=false`. Kirimkan satu wajah yang jelas dan menghadap ke depan per gambar untuk hasil terbaik. **Penagihan.** Setiap respons `200` menggunakan satu kredit API Pencocokan Wajah (dibayar dari kredit paket atau saldo isi ulang Anda). Jika saldo organisasi tidak dapat mencukupi panggilan, endpoint mengembalikan `403` dengan kesalahan "kredit tidak mencukupi" sebelum pemrosesan gambar apa pun. **Persistensi sesi (`save_api_request`, default `true`).** Jika `true`, panggilan disimpan secara persisten sebagai sesi bertipe API: sesi ini muncul di Business Console, `request_id` yang dikembalikan adalah id sesi sebenarnya yang dapat Anda teruskan ke `GET /v3/session/{sessionId}/decision/`, kedua gambar disimpan sebagai gambar sumber/target pencocokan wajah sesi tersebut, dan webhook `status.updated` dipancarkan ke endpoint webhook yang Anda konfigurasi. Jika `false`, tidak ada yang disimpan dan `request_id` adalah UUID korelasi satu kali yang tidak dapat dicari kemudian. **Indeks pencarian wajah.** Endpoint ini tidak pernah mendaftarkan wajah ke dalam indeks pencarian wajah Anda dan tidak pernah menjalankan skrining daftar blokir atau duplikat — gunakan `POST /v3/passive-liveness/` atau `POST /v3/face-search/` untuk keperluan tersebut. **Sandbox.** Kunci API sandbox melewati semua pemrosesan dan penagihan: setelah validasi permintaan (input yang salah format tetap mengembalikan `400`), endpoint mengembalikan payload tiruan statis `Approved`, tidak ada sesi yang disimpan, dan tidak ada kredit yang digunakan. **Autentikasi.** Kirim kunci API aplikasi Anda di header `x-api-key`. Kredensial yang hilang atau tidak valid mengembalikan `403` (`{"detail": "You do not have permission to perform this action."}`) — API ini tidak pernah mengembalikan `401`. **Batas laju.** Batas bersama untuk 300 permintaan tulis per menit per kunci API di seluruh endpoint POST/PATCH/DELETE; melebihi batas ini mengembalikan `429`. operationId: post_v3face-match parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - user_image - ref_image properties: user_image: type: string format: binary description: >- Gambar wajah nyata atau kandidat yang akan diverifikasi (misalnya swafoto). Kirim satu foto menghadap ke depan dengan wajah subjek terlihat jelas dan pencahayaan baik. Ekstensi yang diizinkan: `tiff`, `jpg`, `jpeg`, `png`, `webp`. Ukuran unggahan maksimum: **5 MB** (file yang lebih besar ditolak dengan `400`). Gambar secara otomatis dikompresi menjadi ~0.5 MB sebelum diproses, sehingga resolusi yang sangat tinggi tidak meningkatkan akurasi. ref_image: type: string format: binary description: >- Gambar wajah referensi untuk dibandingkan (misalnya foto dokumen identitas atau foto yang didaftarkan sebelumnya). Format dan batas ukuran sama seperti `user_image`. face_match_score_decline_threshold: type: number format: float default: 30 minimum: 0 maximum: 100 description: >- Ambang batas kemiripan (0–100) yang menentukan respons `status`. Skor terhitung **pada atau di bawah** nilai ini akan menetapkan `status` menjadi `Declined` dan menambahkan peringatan `LOW_FACE_MATCH_SIMILARITY`; skor yang secara ketat berada di atasnya mengembalikan `Approved`. Nilai default `30` bersifat permisif — naikkan nilainya (misalnya `50`–`60`) untuk verifikasi yang lebih ketat. Nilai di luar 0–100 mengembalikan `400`. example: 50 rotate_image: type: boolean default: false description: >- Jika `true`, layanan mencoba gambar-gambar input dalam kelipatan 90 derajat (0, 90, 180, 270) dan menggunakan orientasi yang menghasilkan deteksi wajah terbaik — berguna untuk pengambilan gambar seluler dengan orientasi EXIF yang hilang. Menambah latensi, jadi aktifkan hanya jika Anda tidak dapat menjamin gambar dalam posisi tegak. example: false save_api_request: type: boolean default: true description: >- Jika `true` (default), menyimpan panggilan sebagai sesi tipe API — terlihat di Business Console, dapat diambil melalui `GET /v3/session/{sessionId}/decision/` menggunakan `request_id` yang dikembalikan, dan diumumkan melalui webhook `status.updated`. Jika `false`, tidak ada yang disimpan dan `request_id` adalah UUID sementara hanya untuk korelasi respons. example: true vendor_data: type: string description: >- String buram opsional (ID pengguna internal, email, UUID Anda…) yang disimpan pada sesi yang dipertahankan dan dikembalikan dalam respons. Gunakan untuk mengorelasikan panggilan API dengan catatan Anda sendiri dan memfilter sesi nantinya. example: user-123 metadata: type: object additionalProperties: true description: >- Objek JSON opsional yang disimpan bersama sesi (saat `save_api_request=true`) dan dikembalikan dalam respons. Dalam permintaan multipart, kirimkan sebagai kolom string yang dikodekan dalam JSON (misalnya `metadata={"flow":"login"}`) — kolom ini akan diuraikan menjadi sebuah objek. example: flow: login device_id: abc123 example: user_image: (binary JPEG/PNG of the live selfie) ref_image: (binary JPEG/PNG of the reference photo) face_match_score_decline_threshold: 50 rotate_image: false save_api_request: true vendor_data: user-123 metadata: flow: login responses: '200': description: >- Pencocokan wajah telah dihitung. `face_match.score` adalah float 0–100 (dua desimal); `status` adalah `Approved` ketika skor secara ketat di atas `face_match_score_decline_threshold`, jika tidak `Declined` dengan peringatan penjelas. Pasangan dengan kemiripan rendah atau tidak dapat dinilai tetap mengembalikan `200` — periksa `face_match.status` dan `face_match.warnings`, bukan hanya kode HTTP. Ketika `save_api_request=true`, `request_id` adalah id sesi yang disimpan. content: application/json: examples: Approved: summary: Orang yang sama — skor di atas ambang batas value: request_id: f9f5a777-8002-44c6-baaf-128bcfd6e226 face_match: status: Approved score: 99.41 user_image: entities: - bbox: - 661 - 728 - 1688 - 2188 confidence: 0.732973 age: 26.91 gender: male race: null best_angle: 0 ref_image: entities: - bbox: - 653 - 745 - 1691 - 2185 confidence: 0.722082 age: 27 gender: male race: null best_angle: 0 warnings: [] vendor_data: user-123 metadata: flow: login created_at: '2026-06-12T01:04:42.763237+00:00' Declined - low similarity: summary: Skor pada atau di bawah ambang batas penolakan value: request_id: 7cdda24e-311a-46d3-a3bb-e5d9b564ce73 face_match: status: Declined score: 24.87 user_image: entities: - bbox: - 661 - 728 - 1688 - 2188 confidence: 0.732973 age: 26.91 gender: male race: null best_angle: 0 ref_image: entities: - bbox: - 156 - 234 - 679 - 898 confidence: 0.717775 age: 41.2 gender: male race: null best_angle: 0 warnings: - risk: LOW_FACE_MATCH_SIMILARITY feature: FACEMATCH additional_data: null log_type: error short_description: Low face match similarity long_description: >- The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch. vendor_data: user-123 metadata: null created_at: '2026-06-12T01:08:19.859116+00:00' schema: type: object properties: request_id: type: string format: uuid description: >- ID sesi yang disimpan saat `save_api_request=true` (dapat digunakan dengan `GET /v3/session/{sessionId}/decision/`); jika tidak, berupa UUID korelasi sementara. face_match: type: object properties: status: type: string enum: - Approved - Declined description: >- `Approved` ketika skor kemiripan secara ketat berada di atas `face_match_score_decline_threshold` dan skor dapat dihitung; `Declined` jika tidak (peringatan menjelaskan alasannya). score: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Skor kemiripan dari 0 hingga 100 — tingkat keyakinan model bahwa kedua gambar menggambarkan orang yang sama. Dibulatkan menjadi dua desimal hanya saat `save_api_request` bernilai true; dengan `save_api_request=false`, nilai float mentah dikembalikan. `null` jika tidak ada pasangan wajah yang dapat dinilai (dengan default `save_api_request=true`); dengan `save_api_request=false`, kondisi yang sama dapat muncul sebagai `score: 0`. Bagaimanapun, peringatan `NO_REFERENCE_IMAGE` akan muncul dan `status` bernilai `Declined`. example: 99.41 user_image: type: object description: Hasil deteksi wajah untuk gambar yang dianalisis. properties: entities: type: array items: type: object properties: bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- Bounding box wajah yang terdeteksi sebagai koordinat piksel `[x_min, y_min, x_max, y_max]` pada gambar yang diproses. example: - 661 - 728 - 1688 - 2188 confidence: type: number format: float minimum: 0 maximum: 1 description: Skor keyakinan deteksi wajah (0–1). example: 0.732973 age: type: number format: float description: >- Usia yang diestimasi oleh model dari wajah yang terdeteksi, dalam tahun. Hanya bersifat informasi — ini tidak memengaruhi keputusan Pencocokan Wajah. example: 26.91 gender: type: string description: >- Jenis kelamin yang diprediksi oleh model dari wajah yang terdeteksi (`male` atau `female`). Hanya bersifat informasi. example: male race: type: string nullable: true description: >- Kolom yang dicadangkan — selalu bernilai `null` dalam respons dari endpoint ini. example: null description: Satu entri per wajah yang terdeteksi. best_angle: type: integer description: >- Rotasi (derajat: 0, 90, 180, atau 270) yang menghasilkan deteksi wajah terbaik. Hanya bernilai bukan nol jika `rotate_image=true` mengoreksi orientasi. example: 0 ref_image: type: object description: >- Hasil deteksi wajah untuk gambar referensi, bentuk yang sama seperti `user_image`. properties: entities: type: array items: type: object properties: bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- Bounding box wajah yang terdeteksi sebagai koordinat piksel `[x_min, y_min, x_max, y_max]` pada gambar yang diproses. example: - 661 - 728 - 1688 - 2188 confidence: type: number format: float minimum: 0 maximum: 1 description: Skor keyakinan deteksi wajah (0–1). example: 0.732973 age: type: number format: float description: >- Usia yang diestimasi oleh model dari wajah yang terdeteksi, dalam tahun. Hanya bersifat informasi — ini tidak memengaruhi keputusan Pencocokan Wajah. example: 26.91 gender: type: string description: >- Jenis kelamin yang diprediksi oleh model dari wajah yang terdeteksi (`male` atau `female`). Hanya bersifat informasi. example: male race: type: string nullable: true description: >- Kolom yang dicadangkan — selalu bernilai `null` dalam respons dari endpoint ini. example: null description: Satu entri per wajah yang terdeteksi. best_angle: type: integer example: 0 warnings: type: array description: >- Kosong jika persetujuan bersih. `NO_REFERENCE_IMAGE` (`error`) — pasangan wajah tidak dapat dinilai; `LOW_FACE_MATCH_SIMILARITY` (`error`) — skor berada pada atau di bawah ambang batas penolakan. Salah satu dari kondisi ini akan menetapkan `status` ke `Declined`. items: type: object properties: risk: type: string enum: - NO_REFERENCE_IMAGE - LOW_FACE_MATCH_SIMILARITY description: Kode risiko yang dapat dibaca mesin. feature: type: string enum: - FACEMATCH description: >- Fitur yang memunculkan peringatan. Selalu `FACEMATCH` pada endpoint ini. additional_data: type: object nullable: true additionalProperties: true description: Selalu `null` untuk peringatan pencocokan wajah. log_type: type: string enum: - error - warning - information description: >- Tingkat keparahan. Peringatan `error` mendorong `status` menjadi `Declined`; entri `warning` dan `information` bersifat anjuran dan tidak pernah menolak dengan sendirinya. short_description: type: string description: >- Ringkasan satu baris yang dapat dibaca manusia tentang risiko. long_description: type: string description: Penjelasan risiko yang mudah dibaca manusia. vendor_data: type: string nullable: true description: Salinan `vendor_data` yang Anda kirimkan, atau `null`. metadata: type: object nullable: true additionalProperties: true description: Salinan objek `metadata` yang Anda kirimkan, atau `null`. created_at: type: string format: date-time description: >- Stempel waktu ISO 8601 (UTC) saat respons dibuat, misalnya `2026-06-12T01:04:42.763237+00:00`. '400': description: >- Kesalahan validasi. Dikembalikan ketika gambar yang diperlukan tidak ada, melebihi 5 MB, memiliki ekstensi yang tidak didukung, atau ketika sebuah opsi berada di luar rentang. Isi respons adalah envelope kesalahan kolom standar DRF: satu array pesan per kolom yang bermasalah. content: application/json: examples: Missing required image: summary: >- `ref_image` (atau `user_image`) tidak disertakan di dalam data formulir value: ref_image: - No file was submitted. Unsupported file extension: summary: Ekstensi file di luar tiff/jpg/jpeg/png/webp value: user_image: - >- File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp. File too large: summary: Unggahan melebihi batas 5 MB value: user_image: - File size should not exceed 5 MB Threshold out of range: summary: '`face_match_score_decline_threshold` di luar rentang 0–100' value: face_match_score_decline_threshold: - Ensure this value is less than or equal to 100. '403': description: >- Izin ditolak. Dikembalikan ketika header `x-api-key` tidak ada, dan juga ketika saldo organisasi pemanggil tidak dapat mencukupi biaya panggilan tersebut; kunci yang salah, dicabut, atau kedaluwarsa mengembalikan `401`. Kunci yang tidak ada mengembalikan `403` dengan `{"detail": ...}`; kunci yang salah, dicabut, atau kedaluwarsa mengembalikan `401`. Kekurangan kredit mengembalikan `403` dengan `{"error": ...}` sebelum pemrosesan gambar apa pun terjadi. content: application/json: examples: Missing or invalid API key: summary: >- Tidak ada header `x-api-key`, atau kuncinya tidak valid/dicabut value: detail: You do not have permission to perform this action. Not enough credits: summary: Saldo organisasi tidak mencukupi untuk panggilan ini value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- Batas laju terlampaui. Endpoint POST/PATCH/DELETE berbagi anggaran 300 permintaan penulisan per menit per kunci API (pembuatan transaksi dan ingesti event memiliki anggaran terpisah sebesar 600). Respons menyertakan header `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, dan `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: Lebih dari 300 permintaan tulis pada menit ini value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -X POST 'https://verification.didit.me/v3/face-match/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'user_image=@./selfie.jpg' \ -F 'ref_image=@./id_portrait.jpg' \ -F 'face_match_score_decline_threshold=50' \ -F 'save_api_request=true' \ -F 'vendor_data=user-123' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.face_match.compare( user_image=open("user_image.jpg", "rb"), ref_image=open("ref_image.jpg", "rb"), face_match_score_decline_threshold=50.0, rotate_image=False, save_api_request=True, vendor_data="user-123", metadata={"flow": "login"}, ) print(result) - lang: javascript label: Node.js source: |- import Didit, { fileFromPath } from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.faceMatch.compare({ user_image: await fileFromPath("user_image.jpg"), ref_image: await fileFromPath("ref_image.jpg"), face_match_score_decline_threshold: 50.0, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "login" }, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.FaceMatch.Compare(ctx, didit.FaceMatchCompareParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tRefImage: didit.FileFromPath(\"ref_image.jpg\"),\n\tFaceMatchScoreDeclineThreshold: didit.Float(50.0),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"login\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.nio.file.Path; import java.util.Map; import me.didit.Didit; import me.didit.types.FaceMatchCompareParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.faceMatch().compare(FaceMatchCompareParams.builder() .userImage(Path.of("user_image.jpg")) .refImage(Path.of("ref_image.jpg")) .faceMatchScoreDeclineThreshold(50.0) .rotateImage(false) .saveApiRequest(true) .vendorData("user-123") .metadata(Map.of("flow", "login")) .build()); System.out.println(result); - lang: php label: PHP source: |- faceMatch->compare([ 'user_image' => File::fromPath('user_image.jpg'), 'ref_image' => File::fromPath('ref_image.jpg'), 'face_match_score_decline_threshold' => 50.0, 'rotate_image' => false, 'save_api_request' => true, 'vendor_data' => 'user-123', 'metadata' => ['flow' => 'login'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.face_match.compare( user_image: Pathname("user_image.jpg"), ref_image: Pathname("ref_image.jpg"), face_match_score_decline_threshold: 50.0, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "login" } ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Collections.Generic; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.FaceMatch.CompareAsync(new FaceMatchCompareParams { UserImage = FileUpload.FromPath("user_image.jpg"), RefImage = FileUpload.FromPath("ref_image.jpg"), FaceMatchScoreDeclineThreshold = 50.0, RotateImage = false, SaveApiRequest = true, VendorData = "user-123", Metadata = new Dictionary { ["flow"] = "login" }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Kunci API aplikasi Anda, dari Developers -> API keys di Business Console. Kunci utama memiliki akses penuh. Kunci bernama dapat diberi cakupan: none, read, atau write per sumber daya, dibatasi pada beberapa alur kerja atau pada sesi yang disetujui, pada daftar alamat IP, dan pada tanggal kedaluwarsa. 401 berarti kuncinya salah, dicabut, atau kedaluwarsa; 403 berarti tidak ada kunci yang dikirimkan, kunci tidak memiliki akses ke sumber daya atau tindakan ini, atau permintaan datang dari alamat di luar daftar IP-nya; 404 pada rute sesi berarti sesi berada di luar alur kerja atau status kunci tersebut. Kunci tanpa akses media menerima URL gambar, video, dan PDF sebagai null, dan kunci tanpa izin tulis sesi menerima tautan sesi dan token sebagai null. Lihat https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.