Add facial age estimation to your web app with YouAge Written on 25 Aug 2026

You can call the YouAge API in three lines and get an apparent age back. The harder question is what to build around those three lines so the result holds up outside a demo. This tutorial is for developers and engineers who want a working age-estimation app, plus a clear view of where a demo stops and a compliant age-assurance service begins.

In a nutshell

Calling YouAge is simple. One selfie in, an estimated age and an image-quality status out, in under a second.
The engineering that matters sits around that call. Keep your API key on a backend you control, and let that server talk to the API.
Act on the image status first. When YouAge returns VALID_IMAGE the estimate is usable, and other statuses tell the user how to retake the photo.
A challenge age lets the demo route users, and it's a starting point. A production age check adds liveness, a fallback, monitoring, and legal sign-off.

What you'll build

The demo accepts a selfie, sends it to a backend, calls the YouAge API, and displays the estimated apparent age alongside the image-validation status. It also shows a simple routing message based on a challenge age you configure.

Think of it as the API layer of an age check, built the right way. A full production system wraps more around it: liveness (proof that a real person is in front of the camera, not a photo or a video), injection resistance, consent and transparency, a second method, rate limits, retry state, audit records, accessibility, and jurisdiction-specific thresholds. This tutorial keeps that boundary in view, whether you're gating signups on a dating app, access to an adult site, or age-appropriate features on a social platform.

The API key stays on your backend

Your Youverse API key belongs on the server, not in the browser. The browser submits the image to a backend you control. That backend validates the file type and size, converts the binary image to Base64, calls YouAge with the private x-api-key, and returns only the age and status the interface needs.

Browser camera/upload | v
Your Node.js backend -- private x-api-key --> YouAge API | v
age + validation status + local routing message

Routing through your own server also gives you one place for the production controls that come later, such as authentication, rate limiting, CSRF protection, session state, liveness orchestration, and privacy-safe logging.

Step 1. Create the project

Create a folder and install Express, Multer, and Axios.

mkdir youage-demo
cd youage-demo
npm init -y
npm install express multer axios dotenv helmet express-rate-limit
mkdir public

Add YOUVERSE_API_KEY=your-key to a local .env file, then add .env to .gitignore. Never place the key in frontend JavaScript or commit it to source control.

Step 2. Build the backend

The package ships a complete server.js. The part that matters is the server-side request.

const payload = { image: req.file.buffer.toString('base64') };
const response = await axios.post( 'https://face-analysis.youverse.id/v1/age', payload, { headers: { 'x-api-key': process.env.YOUVERSE_API_KEY } }
);

The route rejects oversized or unsupported files, applies rate limiting, and avoids logging image content. It returns the API status so the frontend can tell the user whether they need better lighting, a closer face, or a single-person frame.

Step 3. Build the frontend

The sample public/index.html uses a file input with camera capture support.

<input id="image" type="file" accept="image/png,image/jpeg,image/bmp" capture="user">

JavaScript submits the file as multipart form data. The interface waits for a VALID_IMAGE status before it shows any pass or fail. For quality errors, it maps the machine status to a plain instruction, so the app only acts on an estimate it can trust.

Step 4. Add demonstration routing

The backend sample defines a CHALLENGE_AGE environment variable, the age at which the demo changes its response. If the estimate meets or exceeds that value, the demo route continues. If it falls below, the demo asks for a stronger method.

Treat the routing as a demonstration. A real service should validate the challenge age against its own population, set the legal threshold separately, account for estimates that skew high or low, and wire in the fallback before it controls access.

Step 5. Run and test

Start the server.

node server.js

Open http://localhost:3000, submit a clear single-face image, and check the returned age and validation status. Then try deliberately poor images: low light, blur, a face near the edge, and multiple faces. A useful integration test confirms that each status produces an actionable instruction and that the server rejects files beyond its configured limit.

What to add before you go to production

Harden the basics first. A production build should use TLS, authenticated sessions where appropriate, CSRF protection, strict content limits, malware-safe file handling, rate limiting, and secure secret management. Keep images, Base64 payloads, and unnecessary personal identifiers out of your logs, and document and enforce a retention schedule.

Then close the gaps a single estimate leaves open. Add YouLive or an equivalent liveness and injection control if a user could present someone else's photo or synthetic media, and bind the liveness and age calls to one session. Offer a wallet, document, or approved alternative for users the model is unsure about. Store a narrow decision record rather than the raw selfie, unless a defined purpose and lawful basis require more.

Your production decision checklist

Before you connect the demo to real access control, answer these.

What legal and challenge ages apply?
What is the measured minor pass-through rate in our capture environment?
What happens below the challenge age?
How are quality retries limited?
What stops photographs, replays and injected media?
What alternative exists for users without a camera or who dispute the estimate?
What data is retained, by whom and for how long?
How are outcomes monitored by device and relevant cohort?

The code is the smallest item on that list. That's why this tutorial spends its time on architecture and governance, because they're what turn a working call into a defensible age check.

Where Youverse stands

We think the honest version of this tutorial matters more than a faster one. YouAge is deliberately simple to call: one Base64 selfie in, an estimated apparent age and an image-validation status out, in under a second, with no biometric data stored. That simplicity belongs at the component boundary, and the controls around it belong to your use case. Where you need to confirm a real person is behind the camera, YouLive adds liveness and injection attack detection. The products supply evidence and technical controls, while your service still owns the threshold, the fallback, the retention policy, and any regulatory reporting. Build the demo to learn the API, then design the system around it.

Start building with a free trial

Ready to build it for real? Start a free trial, generate your YouAge API key, and make your first call in minutes.

Frequently asked questions

Why must the API key stay on the backend?

A browser key can be extracted and abused. Server-side calls let you manage the secret, rate-limit requests, validate input, control logging, and enforce policy in one place.

What does VALID_IMAGE mean?

It means a face was detected and the image was suitable for analysis. Other statuses flag quality or framing problems to resolve before you trust the estimate.

Can the demo block under-18 users?

It can demonstrate routing, but production access control needs a validated challenge policy, liveness where needed, a fallback, monitoring, and legal review.

Should the server store the image?

The sample processes it in memory and does not keep it. In production, limit any retention to a documented, necessary, and lawful purpose.