Developers
Face recognition SDK
Embed detection, enrolment, verification and identification directly in your own application — in your process, on your hardware, with the video never leaving it.
- In-process integration, no network hop
- Detection, quality, enrolment, 1:1, 1:N, tracking, liveness
- Offline and air-gapped deployment supported
- Platform and language support confirmed per evaluation
In short
The Ayonix face recognition SDK embeds detection, quality assessment, enrolment, template creation, 1:1 verification, 1:N identification, tracking and liveness into a customer application. Platform builds, language bindings and licensing are confirmed per evaluation rather than published, because support varies by release.
This page describes the integration model, the sequence, and the decisions that determine whether an SDK integration succeeds. It is not an API reference, and it deliberately contains no function names.
That is a considered choice. A developer page that publishes invented identifiers costs whoever copies them a day of confusion and costs the vendor its credibility permanently. The real interface reference is versioned against the build you receive and comes with the evaluation.
What makes biometric integration slow
Developer frustration with biometric SDKs is remarkably consistent across vendors. Each of these is answered below with what this page does about it — including where the honest answer is 'we will tell you in writing rather than publish it'.
Integration takes months because the SDK’s model does not match the application’s.
The conceptual sequence is on this page before any commitment: initialise, session, detect, score, extract, compare, decide, release. If that does not fit your architecture, you find out today rather than in month three.
Documentation is thin, out of date, or behind a sales conversation.
The interface reference is released with an evaluation, and it is versioned against the build you receive. This page does not pretend to be that reference, which is why it contains no invented function names.
Platform support is unclear until a build fails on the target.
Supported operating systems, architectures and language bindings are confirmed in writing for your target before the evaluation starts. No platform matrix is published here, because an unverified one is worse than none.
Licensing terms are opaque and only surface at contract stage.
The licensing model — how licences are issued, what they are bound to, and how they behave offline — is stated in the evaluation agreement rather than discovered at procurement.
Threshold tuning is guesswork with no guidance on what to measure.
Thresholds are set against what each error costs in your application, using measurements from your own data. The accuracy and testing page sets out the method rather than offering a magic number.
There is no quality feedback, so bad captures are compared and produce noise.
Quality assessment is a first-class step. A capture below the floor should be discarded rather than compared, and building that into the integration early prevents most of the false matches that get blamed on the algorithm.
Enrolment and template lifecycle are left entirely to the integrator.
Template creation, storage, protection, re-enrolment and deletion are covered in the integration guidance, because getting them wrong is a data protection problem rather than a bug.
There is no guidance on running it in production at scale.
Threading, concurrency, resource lifetime, versioning and offline operation are part of the evaluation material, because these are what determine whether the integration survives its first busy day.
How it works
The integration sequence
Four phases. The third is where most of the engineering effort goes, and the second is where most of the quality is determined.
-
Initialise
Load licence material and the model set, select the hardware target, and obtain an engine handle held for the process lifetime rather than per request.
Fails when: The engine is initialised per request, and the cost of loading models dominates the latency budget.
-
Enrol
Capture under the conditions the deployment will use, score quality, create templates, and store them under your own protection and retention regime.
Fails when: Enrolment happens under ideal conditions that production never reproduces, and every later comparison inherits the mismatch.
-
Recognise
Detect, score quality, extract a template, compare 1:1 or 1:N, apply the threshold, and return the decision together with the score and threshold that produced it.
Fails when: Quality scoring is skipped for speed, and unusable captures are compared and produce confident nonsense.
-
Operate
Manage resource lifetime, concurrency, version upgrades, licence renewal and template re-enrolment as ongoing responsibilities rather than one-off setup.
Fails when: Handles are never released under error paths, and the process degrades over days rather than failing cleanly.
Capabilities
What the SDK provides
Each capability is listed with the thing it is most often expected to do and does not, because that is the part that causes integration surprises.
Face detection
Locates faces in an image or frame and returns regions with landmarks.
Does not: Does not tell you whether the capture is good enough to compare. That is the next step, and skipping it is the most common integration error.
Quality assessment
Scores a capture so unusable ones can be discarded before extraction.
Does not: Does not repair a poor capture. A low score means ask again, not try harder.
Enrolment and templates
Creates an opaque biometric template from a capture, for storage in your own system.
Does not: Does not store or protect templates for you. Storage, encryption and deletion are your implementation.
1:1 verification
Compares a capture against one enrolled template and returns a similarity.
Does not: Does not return a probability of identity. A similarity score is only interpretable with its threshold.
1:N identification
Searches a gallery and returns ranked candidates.
Does not: Does not behave like 1:1 as the gallery grows. Error rates rise with gallery size, so measure at the real size.
Tracking
Maintains continuity for a face across consecutive frames of one stream.
Does not: Is not cross-camera journey reconstruction, and should not be described to stakeholders as though it were.
Liveness / PAD
Resists photographs, screen replays and masks in supported capture workflows.
Does not: Is not a general guarantee. Resistance is specific to the attack instruments tested for, so specify them.
Attribute estimation
Estimates visible attributes such as accessories, for approved analytics uses.
Does not: Is not verified identity information and must not be used as though it were.
Offline operation
Runs without network connectivity, including in air-gapped environments.
Does not: Does not remove the licence question. Settle offline licence issuance and validation first.
Recognition is available to customer applications through an SDK and an HTTP API
- Source type
- Ayonix first-party statement
- Verified
- 2026-09-11 · Jan Mocary, Chief Technology Officer
What this does not establish
Confirms that an SDK and an HTTP API exist. It does not establish any specific function name, endpoint path, language binding or operating-system build, none of which is published on this site.
Integration sequence
A conceptual sequence, not executable code
Read this as a description of the steps and their order. The identifiers are English descriptions, not Ayonix function names, and nothing below will compile — deliberately.
# CONCEPTUAL SEQUENCE — not executable, not an API reference.
# Function names below are descriptions of steps, not Ayonix identifiers.
1. initialise the engine
← licence material, model set, hardware selection
→ engine handle, held for the process lifetime
2. create a matching session
← gallery reference, threshold, quality floor
→ session handle
3. for each frame or image:
detect faces
→ zero or more face regions with landmarks
score capture quality
→ a quality value per face
→ BELOW THE FLOOR: discard. Do not extract, do not compare.
extract a template
→ an opaque biometric template
compare
1:1 → template vs one enrolled template → similarity
1:N → template vs gallery → ranked candidates
apply the threshold
→ decision, plus the score and the threshold that produced it
4. handle the result
→ emit an event carrying decision, score, threshold, timestamp, source
→ never emit a bare identity without the evidence behind it
5. release the session, then the engine
→ templates zeroed, handles invalidatedThe real interface reference — actual function names, types, error codes and threading rules — is supplied with an SDK evaluation and is versioned against the build you receive. It is not published here because an interface reference that is not tied to a specific build is a source of bugs rather than a convenience.
SDK or API
Which route fits the application
This is usually decided by where the video already is and how many things need to call recognition. Neither route is better in general.
| SDK — in-process | API — service | |
|---|---|---|
| Where recognition runs | Inside your application process | In a service inside your environment |
| Latency | Supported: Lowest — no network hop at all | Partial: Adds a local network round trip |
| Does video leave your application? | Supported: No | Partial: It reaches the service, inside your own network |
| Language flexibility | Partial: Bound to supported bindings | Supported: Any language that speaks HTTP |
| Serving several applications | Partial: Each embeds its own instance | Supported: One deployment serves many callers |
| Operational burden | Versioning inside each application | One service to run, monitor and upgrade |
| Typical fit | A terminal, a gate, an edge device, a single high-throughput application | A back office, several consuming applications, a mixed-language estate |
Many deployments use both: the SDK embedded at the gate where latency matters, and the API for the applications behind it.
Production concerns
What determines whether the integration survives its first busy day
These are covered in the evaluation material because they are where integrations actually fail, long after the first successful match.
Error handling
No face, poor quality, no match, ambiguous match, engine error and licence failure are six outcomes that need six behaviours. Collapsing them into one exception loses the information the application needs to respond correctly — a retry prompt, a fallback, or an alert to operations.
Threading and concurrency
How many streams per process, whether sessions are shared or per-thread, and what is safe to call concurrently. Decide this before writing the integration; retro-fitting concurrency around a single-threaded assumption is expensive and error-prone.
Resource lifetime
Engine and session handles are expensive to create and must be released on every path including error paths. The usual failure is a process that degrades over days rather than failing cleanly, which is much harder to diagnose.
Versioning and upgrades
What changes between versions, whether templates remain compatible, and what re-enrolment would cost at your gallery size. This determines your upgrade path for the life of the product and should be understood before the first deployment.
Licensing
How licences are issued, what they bind to, how they renew, and what happens offline. For an air-gapped deployment this is the first question rather than the last, because it constrains the whole architecture.
Template protection
Templates are biometric personal data. Encrypt at rest, control access, retain only while there is a lawful basis, and delete verifiably. Where the SDK is embedded in your application, implementing this is your responsibility.
SDK integration checklist
Answer these before requesting an evaluation. They determine whether the SDK is the right route at all — and for some applications the honest answer is that the API is a better fit.
-
State the target platform precisely
Operating system, distribution, architecture, and whether a GPU or NPU is available. Supported builds are confirmed against this rather than assumed from a general claim.
-
State the language and runtime you will call from
A native binding, a managed runtime and a scripting language are different integration efforts. Say which before evaluation, so the right binding is supplied.
-
Define the latency budget end to end
Not the matching time in isolation. Capture, decode, detection, extraction, comparison and your own application logic all contribute, and the budget belongs to the whole path.
-
State the gallery size now and at three years
1:N behaviour depends on gallery size. An integration designed around a thousand enrolments may need a different data structure at a million.
-
Decide where templates will live and how they are protected
Storage, encryption at rest, access control, backup and deletion. This is a data protection design rather than an implementation detail, and it is easier to get right first.
-
Decide the concurrency model up front
How many streams, how many threads, whether sessions are shared or per-thread. Retro-fitting concurrency around a single-threaded assumption is expensive.
-
Plan version upgrades and template compatibility
What happens to existing templates when the engine version changes, and whether re-enrolment is required. This determines your upgrade path for the life of the product.
-
Confirm offline and licence behaviour
How licences are issued and validated, and what happens with no network. For air-gapped deployments this must be settled before any other work.
-
Design error handling for every failure mode
No face, poor quality, no match, ambiguous match, engine error and licence failure are six different outcomes that deserve six different behaviours, not one exception.
-
Plan the measurement before writing the integration
What you will measure, on what data, and what threshold you will settle on. An integration that cannot be measured cannot be tuned.
Frequently asked questions
What programming languages and operating systems does the SDK support?
This page deliberately does not publish a platform matrix. Supported builds, architectures and language bindings vary by release, and publishing an unverified matrix would be exactly the unsupported compatibility claim this site refuses to make. State your target platform, architecture and calling language when requesting an evaluation, and the supported configuration is confirmed in writing before any work begins.
Why is there no example code with real function names on this page?
Because no public Ayonix SDK interface reference was available to verify against when this page was written, and inventing plausible-looking function names would be actively harmful — developers copy code from vendor pages. The conceptual sequence on this page describes the steps and their order, which is what is useful before an evaluation. The real interface reference, versioned against the build you receive, comes with the evaluation.
Should I use the SDK or the API?
The SDK when recognition must run inside your own process — lowest latency, no network hop, and the video never leaves your application. The API when you want one deployment serving several callers, when your application is in a language the SDK does not bind to, or when you would rather operate one service than embed a library in many. The comparison table on this page sets out the trade in full.
What does an SDK evaluation include?
A build for your confirmed target platform, the interface reference for that build, integration guidance covering threading, resource lifetime and error handling, an evaluation licence with stated terms, and access to an integration engineer. The scope and duration are agreed in writing before it starts.
Can the SDK run fully offline?
Ayonix supports on-premise, edge and fully air-gapped deployment, so offline operation is a supported mode rather than a workaround. The detail that matters for an air-gapped build is licence issuance and validation without a network, and that should be settled explicitly at the start of an evaluation because it constrains everything else.
How are biometric templates protected?
A template is an opaque representation rather than an image, but it is still biometric personal data and should be treated as such: encrypted at rest, access-controlled, retained only while there is a lawful basis, and deleted verifiably. Where the SDK is embedded in your application, this is your responsibility to implement, and the integration guidance covers what a defensible implementation looks like.
What happens to templates when the engine version changes?
That depends on the release, and it is one of the questions worth asking before committing to an architecture rather than after. Where a version change requires re-enrolment, that has consequences for a deployed system with a large gallery. The upgrade path and template compatibility for a specific version are confirmed as part of the evaluation.
How do I choose a threshold?
By measuring on your own data, with your own capture conditions, and deciding what each kind of error costs in your application. A false match at a server room door and a false match at a loyalty kiosk are not comparable events. No default threshold is correct for every deployment, and a vendor supplying one without asking about your application has not understood the question. The accuracy and testing page sets out the method.
Related
Where to go next
Face recognition API
The service route: one deployment, many callers, any language.
Accuracy and testing
How to measure and where to set a threshold, on your own data.
Edge face recognition
Where an embedded SDK typically ends up running.
Liveness and PAD
What to specify before accepting a liveness capability as delivered.
Privacy and governance
Template protection, retention and deletion as design requirements.
On-premise deployment
Sizing the hardware an embedded integration will run on.
Next step
Request an SDK evaluation
Tell us the target platform, the calling language, the latency budget and the gallery size. What comes back is a supported-configuration confirmation and an evaluation scope — not a brochure, and not a platform matrix we have not tested.