face-api.js

library0.22.2jsnpmunverified

face-api.js is a robust JavaScript API designed for performing real-time face detection, face recognition, face landmark detection, face expression recognition, and age and gender estimation. It is built on top of the TensorFlow.js core library, enabling these advanced computer vision capabilities directly within web browsers and Node.js environments. The current stable version is 0.22.2. While a strict release cadence isn't explicitly stated, the project appears actively maintained with regular updates and tutorials, often aligning with TensorFlow.js advancements. Its key differentiator is providing a high-level, easy-to-use API over complex TensorFlow.js operations, simplifying the integration of sophisticated facial analysis features into JavaScript applications without requiring deep machine learning expertise. It also provides pre-trained models for various tasks, abstracting away the complexities of model management.

ai-ml

npm install face-api.js

package ↗

INSTALL

IMPORT

SIG · FACE-API.JS

face-api.js

ai-mljavascriptv0.22.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

faceapi

✓ import * as faceapi from 'face-api.js'

✗ import faceapi from 'face-api.js'

The library primarily uses a namespace import for its core functionality, providing access to all methods and utilities via `faceapi.*`.

nets

✓ import { nets } from 'face-api.js'

Provides access to the pre-trained neural networks (e.g., `nets.tinyFaceDetector`, `nets.faceRecognitionNet`) which must be loaded before use. These models reside under the `nets` export.

draw

✓ import { draw } from 'face-api.js'

Contains utility functions for visualizing detection results, landmarks, and expressions directly onto an HTML canvas element (e.g., `draw.drawDetections`, `draw.drawFaceLandmarks`).

createCanvasFromMedia

✓ import { createCanvasFromMedia } from 'face-api.js'

A utility function that creates an HTML canvas element from a media source (like an HTMLImageElement or HTMLVideoElement), useful for processing and drawing.

This quickstart initializes all necessary face-api.js models, starts a webcam stream, and continuously performs real-time face detection, landmark identification, expression recognition, and age/gender estimation, drawing the results onto an HTML canvas overlaid on the video feed.

import * as faceapi from 'face-api.js'; const video = document.getElementById('video') as HTMLVideoElement; const canvas = document.getElementById('overlay') as HTMLCanvasElement; async function initializeFaceApi() { // Ensure models are served from a public path (e.g., /models folder) await Promise.all([ faceapi.nets.tinyFaceDetector.load('/models'), faceapi.nets.faceLandmark68Net.load('/models'), faceapi.nets.faceRecognitionNet.load('/models'), faceapi.nets.faceExpressionNet.load('/models'), faceapi.nets.ageGenderNet.load('/models') ]); console.log('All face-api.js models loaded successfully.'); startWebcamStream(); } async function startWebcamStream() { try { const stream = await navigator.mediaDevices.getUserMedia({ video: true }); video.srcObject = stream; video.onloadedmetadata = () => { // Set canvas dimensions to match video const displaySize = { width: video.width, height: video.height }; faceapi.matchDimensions(canvas, displaySize); setInterval(async () => { const detections = await faceapi.detectAllFaces(video, new faceapi.TinyFaceDetectorOptions()) .withFaceLandmarks() .withFaceExpressions() .withAgeAndGender() .withFaceDescriptors(); const resizedDetections = faceapi.resizeResults(detections, displaySize); canvas.getContext('2d')?.clearRect(0, 0, canvas.width, canvas.height); faceapi.draw.drawDetections(canvas, resizedDetections); faceapi.draw.drawFaceLandmarks(canvas, resizedDetections); faceapi.draw.drawFaceExpressions(canvas, resizedDetections); resizedDetections.forEach(detection => { const { age, gender, genderProbability } = detection; new faceapi.draw.DrawTextField( [ `${faceapi.utils.round(age, 0)} years`, `${gender} (${faceapi.utils.round(genderProbability)})` ], detection.detection.box.bottomLeft ).draw(canvas); }); }, 100); // Run detection every 100ms }; } catch (err) { console.error("Error accessing webcam or initializing Face API:", err); } } document.addEventListener('DOMContentLoaded', initializeFaceApi);

Debug

Known issues

breakingModel loading paths are crucial and frequently cause issues. Models must be hosted on a web server at a path accessible to your application (e.g., `/models`). Direct file system access will fail in browsers.

fix

Ensure the 'models' directory is served statically by your web server, and the `.load()` methods point to the correct URL (e.g., `faceapi.nets.modelName.load('/models')`).

affects: >=0.19.0

gotchaPerformance can vary drastically based on the client device's hardware (CPU/GPU) and the chosen TensorFlow.js backend. Using the 'tiny' models and WebGL backend is generally recommended for browsers.

fix

For browsers, ensure `@tensorflow/tfjs-backend-webgl` is installed and initialized. For Node.js, use `@tensorflow/tfjs-node` or `@tensorflow/tfjs-node-gpu`. Opt for `TinyFaceDetectorOptions` for faster, albeit slightly less accurate, detections.

affects: >=0.19.0

gotchaIf running in Node.js, you must explicitly import and register a TensorFlow.js backend (e.g., `require('@tensorflow/tfjs-node')` or `import '@tensorflow/tfjs-node'`) before loading any `face-api.js` models.

fix

At the top of your Node.js entry file, include `import '@tensorflow/tfjs-node';` or `require('@tensorflow/tfjs-node');` to activate the backend.

affects: >=0.19.0

deprecatedOlder versions of face-api.js and its examples might use CommonJS `require()` syntax. While some versions might still support it, modern JavaScript applications and newer versions of the library primarily target ES Modules.

fix

Always prefer ES Module `import * as faceapi from 'face-api.js'` for consistency and future compatibility, especially when using bundlers like Webpack or Vite.

affects: <0.22.0

Errors

Common errors & fixes

Error: No backend registered for 'webgl'

The TensorFlow.js WebGL backend was not imported or initialized, preventing GPU acceleration in the browser.

fix

Ensure `@tensorflow/tfjs-backend-webgl` is installed and imported in your project (e.g., `import '@tensorflow/tfjs-backend-webgl';`). If running in Node.js, import `@tensorflow/tfjs-node` instead.

Failed to load model from '/models/ssd_mobilenetv1_model_weights_manifest.json' - 404 Not Found

The pre-trained models are not accessible at the specified path on the web server.

fix

Verify that the 'models' directory is correctly placed in your public assets folder and served by your web server. The path provided to `load()` methods (e.g., `/models`) must match the actual URL where the model files are hosted.

TypeError: Cannot read properties of undefined (reading 'detectAllFaces') or 'faceapi is not defined'

The `face-api.js` library or its `faceapi` namespace was not correctly imported or is not available in the current scope when trying to call its methods.

fix

Ensure you are using the correct `import * as faceapi from 'face-api.js'` syntax and that the import statement is executed before any `faceapi` calls. For CommonJS, use `const faceapi = require('face-api.js');` for older versions.

TypeError: video.getContext is not a function

Attempting to call `getContext` on a video element instead of a canvas element.

fix

Ensure you are targeting an HTMLCanvasElement for drawing operations (e.g., `canvas.getContext('2d')`) and not an HTMLVideoElement.

Upgrade

Version history

0.22.2latest on npm

Audit

Dependencies

@tensorflow/tfjs-corerequiredRequired as the core TensorFlow.js library. A TF.js backend (e.g., @tensorflow/tfjs-backend-webgl or @tensorflow/tfjs-node) must also be installed and initialized based on the target environment.

Agent activity

5 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://www.npmjs.com/package/face-api.js ↗