# C API Reference

The C API provides a plain C interface to the Face Verification Library, suitable for integration with C programs and other languages through FFI.

# Opaque Types

# FVLFaceVerifier

typedef struct FVLFaceVerifier FVLFaceVerifier;

Opaque handle to a FaceVerifier instance.

# FVLFace

typedef struct FVLFace FVLFace;

Opaque handle to a Face instance.

# FaceVerifier Functions

# fvl_face_verifier_new

FVLFaceVerifier* fvl_face_verifier_new(const char* model_file, int max_concurrency, char** errorMessage);

Creates a new FaceVerifier instance. Loads the model file and sets up processing.

Parameter	Type	Description
model_file	`const char*`	Path to the `.realZ` model file
max_concurrency	`int`	Maximum allowed concurrency. 0 means automatic (all cores)
errorMessage	`char**`	Output: set to error message on failure, `NULL` on success. Caller must `free()`. Pass `NULL` to skip.

Returns: Pointer to the new instance, or NULL on failure.

# fvl_face_verifier_free

void fvl_face_verifier_free(FVLFaceVerifier* verifier);

Frees a FaceVerifier instance.

Parameter	Type	Description
verifier	`FVLFaceVerifier*`	Instance to free

# fvl_face_verifier_detect_faces

void fvl_face_verifier_detect_faces(FVLFaceVerifier* verifier, const FVLImageHeader* image_header,
                                     FVLDetectFacesCallback callback, void* user_data);

Detects faces on an image asynchronously. The callback is invoked with the result.

Parameter	Type	Description
verifier	`FVLFaceVerifier*`	FaceVerifier instance
image_header	`const` `FVLImageHeader*`	Image descriptor
callback	`FVLDetectFacesCallback`	Callback invoked with the result
user_data	`void*`	User data passed to the callback

The image data is copied internally — it is safe to free the data after the call. This call is non-blocking.

# fvl_face_verifier_embed_face

void fvl_face_verifier_embed_face(FVLFaceVerifier* verifier, const FVLFace* face,
                                   FVLEmbedFaceCallback callback, void* user_data);

Computes the embedding of a detected face asynchronously.

Parameter	Type	Description
verifier	`FVLFaceVerifier*`	FaceVerifier instance
face	`const` `FVLFace*`	The previously detected face
callback	`FVLEmbedFaceCallback`	Callback invoked with the result
user_data	`void*`	User data passed to the callback

# fvl_face_verifier_compare_faces

FVLMatch fvl_face_verifier_compare_faces(FVLFaceVerifier* verifier,
                                          const float* embedding1, int size1,
                                          const float* embedding2, int size2);

Compares two face embeddings.

Parameter	Type	Description
verifier	`FVLFaceVerifier*`	FaceVerifier instance
embedding1	`const float*`	First face embedding
size1	`int`	Size of the first embedding
embedding2	`const float*`	Second face embedding
size2	`int`	Size of the second embedding

Returns: FVLMatch — match result with similarity metric.

# fvl_face_verifier_get_concurrent_calculations

int fvl_face_verifier_get_concurrent_calculations(const FVLFaceVerifier* verifier);

Returns the approximate number of calculations currently in-flight.

Parameter	Type	Description
verifier	`const` `FVLFaceVerifier*`	FaceVerifier instance

Returns: int — number of concurrent calculations.

# fvl_face_verifier_get_model_name

char* fvl_face_verifier_get_model_name(const FVLFaceVerifier* verifier);

Returns the name (version, etc.) of the loaded model.

Parameter	Type	Description
verifier	`const` `FVLFaceVerifier*`	FaceVerifier instance

Returns: char* — model name string. Caller must free() the returned string.

# fvl_face_verifier_get_sdk_version

FVLVersion fvl_face_verifier_get_sdk_version();

Returns the SDK version.

Returns: FVLVersion — SDK version.

# fvl_face_verifier_get_sdk_version_string

char* fvl_face_verifier_get_sdk_version_string();

Returns the SDK version as a string.

Returns: char* — version string. Caller must free() the returned string.

# Face Functions

# fvl_face_new

FVLFace* fvl_face_new(const FVLImageHeader* image_header, const FVLPoint2d* landmarks,
                       int num_landmarks, const FVLBoundingBox* bbox, float confidence,
                       char** errorMessage);

Creates a Face object to support 3rd party face detectors.

Parameter	Type	Description
image_header	`const` `FVLImageHeader*`	Image descriptor
landmarks	`const` `FVLPoint2d*`	Face landmarks array
num_landmarks	`int`	Number of landmarks
bbox	`const` `FVLBoundingBox*`	Face bounding box
confidence	`float`	Detection confidence
errorMessage	`char**`	Output: error message on failure. Caller must `free()`. Pass `NULL` to skip.

Returns: Pointer to the new Face instance, or NULL on failure.

# fvl_face_copy

FVLFace* fvl_face_copy(const FVLFace* other);

Creates a copy of a Face instance.

Parameter	Type	Description
other	`const` `FVLFace*`	Face to copy

Returns: Pointer to the new Face copy, or NULL on failure.

# fvl_face_free

void fvl_face_free(FVLFace* face);

Frees a Face instance.

Parameter	Type	Description
face	`FVLFace*`	Face to free

# fvl_face_detection_quality

FVLDetectionQuality fvl_face_detection_quality(const FVLFace* face);

Returns the detection quality of the face.

Parameter	Type	Description
face	`const` `FVLFace*`	Face instance

Returns: FVLDetectionQuality

# fvl_face_bounding_box

FVLBoundingBox fvl_face_bounding_box(const FVLFace* face);

Returns the bounding box of the face.

Parameter	Type	Description
face	`const` `FVLFace*`	Face instance

Returns: FVLBoundingBox

# fvl_face_confidence

float fvl_face_confidence(const FVLFace* face);

Returns the confidence value of the face.

Parameter	Type	Description
face	`const` `FVLFace*`	Face instance

Returns: float — detection confidence.

# fvl_face_landmarks

FVLPoint2dArray* fvl_face_landmarks(const FVLFace* face);

Returns the landmarks of the face.

Parameter	Type	Description
face	`const` `FVLFace*`	Face instance

Returns: FVLPoint2dArray* — landmark array. Caller must free() the returned array.

# Data Types

# FVLPoint2d

typedef struct FVLPoint2d {
    float x;
    float y;
} FVLPoint2d;

Field	Type	Description
x	`float`	X coordinate of the point
y	`float`	Y coordinate of the point

# FVLPoint2dArray

typedef struct FVLPoint2dArray {
    int count;
    FVLPoint2d* points;
} FVLPoint2dArray;

Field	Type	Description
count	`int`	Number of points
points	`FVLPoint2d*`	Pointer to the array of points

# FVLBoundingBox

typedef struct FVLBoundingBox {
    int x;
    int y;
    int width;
    int height;
} FVLBoundingBox;

Field	Type	Description
x	`int`	X coordinate of the top-left corner
y	`int`	Y coordinate of the top-left corner
width	`int`	Width in pixels
height	`int`	Height in pixels

# FVLImageHeader

typedef struct FVLImageHeader {
    const uint8_t* data;
    int width;
    int height;
    int stride;
    FVLImageFormat format;
} FVLImageHeader;

Field	Type	Description
data	`const uint8_t*`	Pointer to the byte array of the image
width	`int`	Width of the image in pixels
height	`int`	Height of the image in pixels
stride	`int`	Length of one row of pixels in bytes (e.g., `3*width + padding`)
format	`FVLImageFormat`	Image pixel format

# FVLMatch

typedef struct FVLMatch {
    float similarity;
} FVLMatch;

Field	Type	Description
similarity	`float`	Similarity score between the two faces

# FVLVersion

typedef struct FVLVersion {
    int major;
    int minor;
    int patch;
} FVLVersion;

Field	Type	Description
major	`int`	Major version number
minor	`int`	Minor version number
patch	`int`	Patch version number

# FVLFaceArray

typedef struct FVLFaceArray {
    int count;
    FVLFace** faces;
} FVLFaceArray;

Field	Type	Description
count	`int`	Number of faces
faces	`FVLFace**`	Pointer to the array of face pointers

# FVLFloatArray

typedef struct FVLFloatArray {
    int count;
    float* data;
} FVLFloatArray;

Field	Type	Description
count	`int`	Number of floats
data	`float*`	Pointer to the array of floats

# Enumerations

# FVLImageFormat

typedef enum FVLImageFormat {
    FVLImageFormatGrayscale = 0,
    FVLImageFormatRGB       = 1,
    FVLImageFormatRGBA      = 2,
    FVLImageFormatBGR       = 3,
    FVLImageFormatBGRA      = 4,
} FVLImageFormat;

Value	Description
`FVLImageFormatGrayscale`	8-bit grayscale
`FVLImageFormatRGB`	24-bit RGB
`FVLImageFormatRGBA`	32-bit RGBA or RGB with padding
`FVLImageFormatBGR`	24-bit BGR
`FVLImageFormatBGRA`	32-bit BGRA or BGR with padding

# FVLDetectionQuality

typedef enum FVLDetectionQuality {
    FVLDetectionQualityGood        = 0,
    FVLDetectionQualityBadQuality  = 1,
    FVLDetectionQualityMaybeRolled = 2,
} FVLDetectionQuality;

Value	Description
`FVLDetectionQualityGood`	No issues detected
`FVLDetectionQualityBadQuality`	Bad quality detected
`FVLDetectionQualityMaybeRolled`	Face may be rolled; embeddings could be incorrect

# Callback Types

# FVLDetectFacesCallback

typedef void (*FVLDetectFacesCallback)(void* user_data, FVLFaceArray* faces, const char* error_msg);

Callback for face detection results.

Parameter	Type	Description
user_data	`void*`	User data passed to the detection function
faces	`FVLFaceArray*`	Array of detected faces. Valid only during the callback.
error_msg	`const char*`	Error message if failed, `NULL` on success. Valid only during the callback.

# FVLEmbedFaceCallback

typedef void (*FVLEmbedFaceCallback)(void* user_data, FVLFloatArray* embedding, const char* error_msg);

Callback for face embedding results.

Parameter	Type	Description
user_data	`void*`	User data passed to the embedding function
embedding	`FVLFloatArray*`	Embedding vector. Valid only during the callback.
error_msg	`const char*`	Error message if failed, `NULL` on success. Valid only during the callback.

Important: The faces/embedding and error_msg parameters are only valid during the callback execution. Copy any data you need to retain before the callback returns.

# Memory Management Summary

Function Returns	Must Free?	How
`fvl_face_verifier_new()`	Yes	`fvl_face_verifier_free()`
`fvl_face_new()`	Yes	`fvl_face_free()`
`fvl_face_copy()`	Yes	`fvl_face_free()`
`fvl_face_landmarks()`	Yes	`free()`
`fvl_face_verifier_get_model_name()`	Yes	`free()`
`fvl_face_verifier_get_sdk_version_string()`	Yes	`free()`
`errorMessage` output parameter	Yes	`free()`
Callback parameters	No	Valid only during callback