> ## 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. # API Estimasi Usia: Verifikasi Usia Berbasis Swafoto > API Didit untuk estimasi usia berbasis AI dengan deteksi liveness pasif. Tanpa ID, inferensi sub-2s, harga per penggunaan. POST /v3/age-estimation/ ## OpenAPI ````yaml id/openapi-25.json POST /v3/age-estimation/ 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/age-estimation/: post: tags: - Standalone APIs summary: Estimasi Usia (usia wajah + deteksi liveness pasif) description: >- Estimasi usia seseorang dari satu foto wajah dan jalankan pemeriksaan liveness pasif dalam panggilan yang sama — mengembalikan `age_estimation` yang diprediksi model (dalam tahun), `score` liveness (0–100), dan `status` `Approved`/`Declined`. Usia ini **diprediksi model dari wajah, bukan diverifikasi terhadap dokumen** — gunakan untuk pembatasan usia dan pemeriksaan tanpa hambatan, bukan sebagai bukti usia yang sah. **Cara kerjanya.** Gambar dianalisis untuk mendeteksi wajah (atur `rotate_image=true` jika hasil pengambilan gambar miring atau terbalik); setiap wajah yang terdeteksi mendapatkan estimasi usia, dan wajah terbesar di dalam bingkai menentukan `age_estimation`. Secara paralel, model liveness pasif menilai apakah foto menampilkan orang sungguhan (tidak memerlukan tantangan pengguna) dan mendeteksi serangan presentasi (foto dari foto, layar, topeng). Kirim satu wajah yang jelas, menghadap ke depan, dan berpenerangan baik per gambar untuk hasil terbaik. **Logika keputusan.** Setiap peringatan menghasilkan penolakan: `status` menjadi `Approved` hanya jika larik `warnings` kosong. `score` liveness pada atau di bawah `face_liveness_score_decline_threshold` (default `30`) menambahkan `LOW_LIVENESS_SCORE`; serangan yang terdeteksi menambahkan `LIVENESS_FACE_ATTACK`; tidak ada wajah yang ditemukan oleh model liveness menambahkan `NO_FACE_DETECTED`; tidak ada usia wajah yang dapat diestimasi menambahkan `AGE_NOT_DETECTED` (`age_estimation` bernilai `null`); estimasi usia di bawah `age_estimation_decline_threshold` (default `18`) menambahkan `AGE_BELOW_MINIMUM`. Usia yang mendekati ambang batas Anda sebaiknya dialihkan ke verifikasi berbasis dokumen — tingkat kesalahan model meningkat untuk wajah yang mendekati batas tersebut. **Penagihan.** Setiap respons `200` menggunakan satu kredit API Estimasi Usia (dibayar dari kredit paket atau saldo isi ulang Anda). Ketika saldo organisasi tidak mencukupi untuk panggilan tersebut, endpoint mengembalikan `403` dengan kesalahan kredit tidak mencukupi sebelum pemrosesan gambar apa pun. **Persistensi sesi (`save_api_request`, default `true`).** Jika bernilai `true`, panggilan disimpan sebagai sesi tipe API: sesi tersebut muncul di Business Console, `request_id` yang dikembalikan adalah id sesi sebenarnya yang dapat Anda teruskan ke `GET /v3/session/{sessionId}/decision/` (hasilnya ditampilkan di sana dalam `liveness_checks[]`, dengan `features: ["AGE_ESTIMATION"]`), potongan wajah dan gambar referensi disimpan, embedding wajah ditambahkan ke indeks wajah aplikasi Anda (digunakan oleh pencarian wajah dan deteksi duplikat), dan webhook `status.updated` dikirimkan. Jika bernilai `false`, tidak ada yang disimpan dan `request_id` merupakan UUID korelasi sekali pakai yang tidak dapat dicari kemudian. **Sandbox.** Kunci API sandbox melewati semua pemrosesan dan penagihan: setelah validasi permintaan (input yang salah format tetap mengembalikan `400`), endpoint mengembalikan payload tiruan `Approved` statis (`age_estimation: 30`, tanpa peringatan), 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.** Anggaran tulis bersama sebesar 300 permintaan/menit per kunci API di semua endpoint POST/PATCH/DELETE; melampauinya akan mengembalikan `429`. operationId: post_v3age-estimation parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - user_image properties: user_image: type: string format: binary description: >- Foto wajah yang akan dianalisis (misalnya swafoto). Kirimkan satu foto menghadap ke depan dengan wajah subjek terlihat jelas dan dengan pencahayaan yang baik. Ekstensi yang diizinkan: `tiff`, `jpg`, `jpeg`, `png`, `webp` (tanpa PDF). Ukuran unggahan maksimum: **5 MB** (file yang lebih besar ditolak dengan `400`). Gambar secara otomatis dikompresi menjadi ~0.3 MB sebelum diproses, sehingga resolusi yang sangat tinggi tidak meningkatkan akurasi. face_liveness_score_decline_threshold: type: number format: float default: 30 minimum: 0 maximum: 100 description: >- Ambang batas liveness (0–100). `score` liveness **pada atau di bawah** nilai ini menambahkan peringatan `LOW_LIVENESS_SCORE` dan menolak. Naikkan untuk anti-spoofing yang lebih ketat; nilai di luar 0–100 mengembalikan `400`. example: 30 age_estimation_decline_threshold: type: integer default: 18 minimum: 0 maximum: 100 description: >- Estimasi usia minimum yang dapat diterima dalam tahun. Estimasi usia **di bawah** nilai ini akan menambahkan peringatan `AGE_BELOW_MINIMUM` dan ditolak. Atur `0` untuk menonaktifkan pemeriksaan usia (panggilan kemudian hanya menjalankan liveness + estimasi usia tanpa keputusan berbasis usia). example: 18 rotate_image: type: boolean default: false description: >- Jika `true`, layanan mencoba 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, diumumkan melalui webhook `status.updated`, dan dengan wajah yang terdeteksi ditambahkan ke indeks wajah aplikasi Anda. 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":"age-gate"}`) — kolom ini akan diuraikan menjadi sebuah objek. example: flow: age-gate example: user_image: (binary JPEG/PNG of the selfie) face_liveness_score_decline_threshold: 30 age_estimation_decline_threshold: 18 rotate_image: false save_api_request: true vendor_data: user-123 metadata: flow: age-gate responses: '200': description: >- Estimasi usia dan deteksi liveness pasif selesai. `age_estimation.age_estimation` adalah usia yang diprediksi model dalam tahun dari wajah terbesar yang terdeteksi (`null` jika tidak ada); `age_estimation.score` adalah skor deteksi liveness pasif (0–100); `status` bernilai `Approved` hanya jika `warnings` kosong. Pengambilan gambar oleh pengguna di bawah umur atau hasil spoofing tetap mengembalikan `200` dengan `status: "Declined"` — periksa isi respons, bukan hanya kode HTTP. Jika `save_api_request=true`, `request_id` adalah ID sesi yang tersimpan. content: application/json: examples: Approved: summary: Wajah nyata orang dewasa — kedua pemeriksaan lolos value: request_id: 0c40ba43-64ab-4e2e-b4b8-7d1f12f81bc1 age_estimation: status: Approved method: PASSIVE score: 97.5 user_image: entities: - age: 27.33 bbox: - 40 - 40 - 100 - 100 confidence: 0.7177750468254089 gender: male best_angle: 0 age_estimation: 27.33 warnings: [] vendor_data: user-123 metadata: flow: age-gate created_at: '2026-06-12T02:24:11.512941+00:00' Declined - age below threshold: summary: >- Usia hasil estimasi di bawah `age_estimation_decline_threshold` value: request_id: 9be41a6f-2f4e-4f57-92f4-b3a4f6f0a1c2 age_estimation: status: Declined method: PASSIVE score: 95 user_image: entities: - age: 16.5 bbox: - 40 - 40 - 100 - 100 confidence: 0.7177750468254089 gender: female best_angle: 0 age_estimation: 16.5 warnings: - risk: AGE_BELOW_MINIMUM feature: LIVENESS additional_data: null log_type: error short_description: Age below minimum long_description: >- The age of the face is below the minimum age threshold for the application. vendor_data: user-123 metadata: null created_at: '2026-06-12T02:26:40.118332+00:00' Declined - liveness too low: summary: >- Skor liveness pada atau di bawah ambang batas penolakan (kemungkinan spoofing) value: request_id: 5f6f2f1f-7c4f-43b9-8d62-0a8f4c2d9e77 age_estimation: status: Declined method: PASSIVE score: 5 user_image: entities: - age: 25 bbox: - 40 - 40 - 100 - 100 confidence: 0.7177750468254089 gender: male best_angle: 0 age_estimation: 25 warnings: - risk: LOW_LIVENESS_SCORE feature: LIVENESS additional_data: null log_type: error short_description: Low liveness score long_description: >- The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data. vendor_data: user-123 metadata: null created_at: '2026-06-12T02:27:02.901547+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. age_estimation: type: object properties: status: type: string enum: - Approved - Declined description: >- `Approved` saat tidak ada peringatan yang dimunculkan; jika tidak `Declined` (setiap peringatan yang dihasilkan endpoint ini berujung pada penolakan). method: type: string enum: - PASSIVE description: >- Metode liveness. Selalu `PASSIVE` pada endpoint ini (gambar tunggal, tanpa tantangan pengguna). score: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Skor liveness pasif dari 0 hingga 100 — tingkat keyakinan model bahwa foto menampilkan orang sungguhan. Dibandingkan dengan `face_liveness_score_decline_threshold`; jika bernilai sama atau di bawahnya, panggilan ditolak dengan `LOW_LIVENESS_SCORE`. Bernilai `null` jika model liveness tidak mengembalikan keyakinan — panggilan tetap ditolak dengan `LOW_LIVENESS_SCORE` karena null dianggap sebagai 0 untuk perbandingan ambang batas. example: 97.5 user_image: type: object description: Hasil deteksi wajah untuk gambar yang dianalisis. properties: entities: type: array description: >- Satu entri per wajah yang terdeteksi. Kosong jika tidak ada wajah yang ditemukan (maka `age_estimation` bernilai `null` dan peringatan `AGE_NOT_DETECTED` ditambahkan). items: type: object properties: age: type: number format: float description: >- Usia wajah ini yang diestimasi oleh model, dalam tahun. example: 27.33 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: - 40 - 40 - 100 - 100 confidence: type: number format: float minimum: 0 maximum: 1 description: Skor keyakinan deteksi wajah (0–1). example: 0.7177750468254089 gender: type: string description: >- Jenis kelamin yang diprediksi oleh model dari wajah yang terdeteksi (`male` atau `female`). Hanya bersifat informasi. example: male best_angle: type: integer nullable: true 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 age_estimation: type: number format: float nullable: true description: >- Usia yang diprediksi model, dalam tahun, dari wajah terdeteksi yang **terbesar**. `null` jika tidak ada usia wajah yang dapat diestimasi (peringatan `AGE_NOT_DETECTED` ditambahkan dan panggilan ditolak). example: 27.33 warnings: type: array description: >- Kosong jika persetujuan bersih. Entri apa pun akan menetapkan `status` ke `Declined`. items: type: object properties: risk: type: string enum: - NO_FACE_DETECTED - LOW_LIVENESS_SCORE - LIVENESS_FACE_ATTACK - AGE_NOT_DETECTED - AGE_BELOW_MINIMUM description: >- Kode risiko yang dapat dibaca mesin. `NO_FACE_DETECTED` — model liveness tidak menemukan wajah; `LOW_LIVENESS_SCORE` — `score` liveness sama dengan atau di bawah `face_liveness_score_decline_threshold`; `LIVENESS_FACE_ATTACK` — serangan presentasi (foto/layar/topeng) terdeteksi; `AGE_NOT_DETECTED` — usia wajah tidak dapat diestimasi; `AGE_BELOW_MINIMUM` — estimasi usia di bawah `age_estimation_decline_threshold`. `NO_FACE_DETECTED` dan `LOW_LIVENESS_SCORE` bersifat saling eksklusif — saat tidak ada wajah yang ditemukan, hanya `NO_FACE_DETECTED` yang dimunculkan. feature: type: string enum: - LIVENESS description: >- Fitur yang memunculkan peringatan. Selalu `LIVENESS` pada endpoint ini. additional_data: type: object nullable: true additionalProperties: true description: Selalu `null` untuk peringatan estimasi usia. log_type: type: string enum: - error description: >- Tingkat keparahan. Setiap peringatan yang dihasilkan endpoint ini adalah `error` dan mengatur `status` menjadi `Declined`. 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. '400': description: >- Kesalahan validasi. Dikembalikan ketika `user_image` tidak ada, melebihi 5 MB, memiliki ekstensi yang tidak didukung, atau ketika ambang batas berada di luar rentang. Isi respons adalah envelope kesalahan kolom standar DRF: satu array pesan per kolom yang bermasalah. content: application/json: examples: Missing user image: summary: '`user_image` tidak disertakan dalam data formulir' value: user_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_liveness_score_decline_threshold` di luar rentang 0–100 value: face_liveness_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/age-estimation/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'user_image=@./selfie.jpg' \ -F 'age_estimation_decline_threshold=18' \ -F 'face_liveness_score_decline_threshold=30' \ -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.age_estimation.estimate( user_image=open("user_image.jpg", "rb"), face_liveness_score_decline_threshold=30.0, age_estimation_decline_threshold=18, rotate_image=False, save_api_request=True, vendor_data="user-123", metadata={"flow": "age-gate"}, ) 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.ageEstimation.estimate({ user_image: await fileFromPath("user_image.jpg"), face_liveness_score_decline_threshold: 30.0, age_estimation_decline_threshold: 18, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "age-gate" }, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.AgeEstimation.Estimate(ctx, didit.AgeEstimationEstimateParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tFaceLivenessScoreDeclineThreshold: didit.Float(30.0),\n\tAgeEstimationDeclineThreshold: didit.Int(18),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"age-gate\"}),\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.AgeEstimationEstimateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.ageEstimation().estimate(AgeEstimationEstimateParams.builder() .userImage(Path.of("user_image.jpg")) .faceLivenessScoreDeclineThreshold(30.0) .ageEstimationDeclineThreshold(18L) .rotateImage(false) .saveApiRequest(true) .vendorData("user-123") .metadata(Map.of("flow", "age-gate")) .build()); System.out.println(result); - lang: php label: PHP source: |- ageEstimation->estimate([ 'user_image' => File::fromPath('user_image.jpg'), 'face_liveness_score_decline_threshold' => 30.0, 'age_estimation_decline_threshold' => 18, 'rotate_image' => false, 'save_api_request' => true, 'vendor_data' => 'user-123', 'metadata' => ['flow' => 'age-gate'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.age_estimation.estimate( user_image: Pathname("user_image.jpg"), face_liveness_score_decline_threshold: 30.0, age_estimation_decline_threshold: 18, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "age-gate" } ) 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.AgeEstimation.EstimateAsync(new AgeEstimationEstimateParams { UserImage = FileUpload.FromPath("user_image.jpg"), FaceLivenessScoreDeclineThreshold = 30.0, AgeEstimationDeclineThreshold = 18, RotateImage = false, SaveApiRequest = true, VendorData = "user-123", Metadata = new Dictionary { ["flow"] = "age-gate" }, }); 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.