velix-sdk 0.1.0a1

Official Python SDK for VELIX Biometrics — facial access control platform

velix-sdk — Python SDK

⚠️ Alpha / pre-release. This SDK targets the real API-key surface implemented in api-velix-identity-core under /v1/api/* (see lib-velix-contracts/openapi/public-api.yaml, task #593/#656). Only 6 endpoints exist today. Do not use in production integrations yet.

Official Python SDK for the VELIX Biometrics platform — facial access control B2B SaaS.

Requirements

• Python 3.11 or 3.12 (3.14 is not supported — onnxruntime has no wheel)

Installation

pip install velix-sdk

Quick Start

from velix import VelixClient
from velix.modules.checkin import CheckinModule

with VelixClient(api_url="https://api.velixbiometrics.com", api_key="vlx_...") as client:
    result = CheckinModule(client).identify(image_base64=frame_base64)
    print(result["matched"])  # True | False

Auth: x-api-key: vlx_<hex> header (alternative: Authorization: Bearer vlx_<hex>). Default client timeout is 30s, overridable via VelixClient(..., timeout=...).

Environment Variables

Variable	Required	Description
VELIX_API_URL	Yes	API base URL (https://api.velixbiometrics.com)
VELIX_API_KEY	Yes	API key (vlx_...)

import os
from velix import VelixClient

client = VelixClient(
    api_url=os.environ["VELIX_API_URL"],
    api_key=os.environ["VELIX_API_KEY"],
)

Modules

Module	Methods	Endpoint
OnboardingModule	enroll()	POST /v1/api/onboarding (scope onboarding:write)
CheckinModule	identify()	POST /v1/api/checkin/identify (scope checkin:write)
LgpdModule	request_deletion()	POST /v1/api/deletion-request (scope lgpd:write)
MeModule	get()	GET /v1/api/me/{personId} (scope me:read)
EventsModule	create_guest(), get_guest()	POST/GET /v1/api/events/{id}/guests[/{guestId}] (scopes events:write/events:read)
PersonsModule	—	not implemented — no such endpoint under /v1/api/*; raises NotImplementedError
TenantsModule	—	not implemented — no such endpoint under /v1/api/*; raises NotImplementedError
TimeModule	—	not implemented — identity-core has no proxy to api-velix-time yet (task #593, follow-up #616); raises NotImplementedError

Onboarding Module

from velix.modules.onboarding import OnboardingModule

onboarding = OnboardingModule(client)
result = onboarding.enroll(
    name="João Silva",
    frames=[frame1_b64, frame2_b64, frame3_b64],
    email="[e-mail]",
    external_id="EMP-001",
)
# {"person_id": ..., "identity_id": ..., "enrolled": True, "frames_processed": 3, ...}

Checkin Module

from velix.modules.checkin import CheckinModule

checkin = CheckinModule(client)

result = checkin.identify(image_base64=frame_base64)
# {"matched": True, "person_id": "uuid", "quality_score": 0.92, "message": "..."}

# With liveness challenge (token from the public HMAC endpoint) and GPS
result = checkin.identify(
    image_base64=frame_base64,
    liveness={"token": nonce, "samples": [{"action": "center", "imageBase64": sample_b64}]},
    latitude=-23.5, longitude=-46.6, accuracy=10.0,
)

Liveness score is never returned by the API — only matched/passed booleans.

LGPD Module

from velix.modules.lgpd import LgpdModule

result = LgpdModule(client).request_deletion(person_id="uuid")
# {"protocol_number": "...", "message": "..."}

Me Module

from velix.modules.me import MeModule

me = MeModule(client).get(person_id="uuid")
# {"id": ..., "name": ..., "email": ..., "phone": ..., "photo_url": ..., "created_at": ...}

Events Module

from velix.modules.events import EventsModule

events = EventsModule(client)

guest = events.create_guest("event-uuid", name="Jane Doe", email="[e-mail]")
# {"id": ..., "eventId": ..., "name": ..., "email": ..., "status": ..., "categoryId": ...}

guest = events.get_guest("event-uuid", "guest-uuid")

Error Handling

from velix.exceptions import VelixAuthError, VelixNotFoundError, VelixRateLimitError, VelixAPIError

try:
    result = checkin.identify(image_base64=frame)
except VelixAuthError:
    print("Invalid API key")
except VelixNotFoundError as e:
    print(f"Not found: {e}")
except VelixRateLimitError as e:
    print("Rate limited")
except VelixAPIError as e:
    print(f"HTTP {e.status_code}: {e.message}")

Running Tests

pip install -e ".[dev]"
pytest
pytest -v --tb=short     # verbose
pytest --cov=velix       # with coverage

Tests run with a mock HTTP server — no running service required.

Local Development

git clone <repo>
pip install -e ".[dev]"
pytest

Get an API Key

Access the dashboard at velixbiometrics.com → Settings → API Keys → New Key.