CUTOS AI Face Service

@cutos/ai-face-service is the CUTOS 4.0 SDK for the Gateway-backed AI face service. It provides face collection creation, registration, lookup, search, comparison, removal, and clearing.

This package does not perform browser-side face detection. Use @cutos/ai-face-detector to detect and capture a face, then send its fullFrame or face image to this service.

Gateway Compatibility

The SDK preserves the existing @cutos/gw-client protocol and the ai-face2 Gateway service. The LWA owns Gateway connection setup and passes its connected IPC instance to FaceService.

By default, the service uses the existing default face collection for the current Gateway. Set lwaName to opt into an LWA-specific collection.

create, register, search, compare, and unregister use the original service protocol. userId, saved images, getByUserId, list, and clear require an ai-face2 deployment that includes the face-record management commands.

Install

npm install @cutos/ai-face-service @cutos/gw-client

Usage

import { CoreAPI } from '@cutos/core'
import { IPC } from '@cutos/gw-client'
import { FaceService } from '@cutos/ai-face-service'

const device = await CoreAPI.getDeviceInfo()
const gateway = new IPC(device.gwUrl, {
  gwi: device.gwi,
  username: device.id,
  token: device.token,
})

const faces = new FaceService(gateway)
await faces.init()

const id = await faces.register(faceImage, { userId: 'u-1001', saveImage: true })
const record = await faces.getByUserId('u-1001', { includeImage: true })
const match = await faces.search(faceImage)
const score = await faces.compare(imageA, imageB)
await faces.unregister(id)

faceImage, imageA, and imageB accept either a raw base64 string or a data:image/...;base64,... URL.

userId is optional, but unique within the selected collection when supplied. Registration images are only persisted when saveImage is true; getByUserId and list only return them when includeImage is true. Search results never return saved registration images. clear() removes every registered face from the selected collection.

const records = await faces.list({ limit: 20 })
await faces.clear()

Development

npm run build
npm pack