Python integration

1. Environment

VERIFAI_BASE_URL=https://verifai.iqtbots.ai
VERIFAI_API_KEY=vf_test_your_secret_here
VERIFAI_COLLECTION_ID=your-collection-uuid

2. Client module

# verifai_client.py
import os
from typing import Any

import requests

BASE_URL = os.environ["VERIFAI_BASE_URL"].rstrip("/")
API_KEY = os.environ["VERIFAI_API_KEY"]
COLLECTION_ID = os.environ["VERIFAI_COLLECTION_ID"]
DEFAULT_THRESHOLD = 0.4


class VerifaiError(Exception):
    def __init__(self, code: str, message: str):
        self.code = code
        self.message = message
        super().__init__(message)


def _headers() -> dict[str, str]:
    return {"Authorization": f"Bearer {API_KEY}"}


def _check(payload: dict[str, Any]) -> dict[str, Any]:
    if not payload.get("success"):
        err = payload.get("error") or {}
        raise VerifaiError(err.get("code", "unknown"), err.get("message", "Verifai request failed"))
    return payload["data"]


def enroll_person(*, external_id: str, image_path: str, display_name: str | None = None) -> dict[str, Any]:
    data = {"external_id": external_id}
    if display_name:
        data["display_name"] = display_name
    with open(image_path, "rb") as image:
        response = requests.post(
            f"{BASE_URL}/api/v1/collections/{COLLECTION_ID}/persons/",
            headers=_headers(),
            data=data,
            files={"image": image},
            timeout=60,
        )
    return _check(response.json())


def verify_person(*, external_id: str, image_path: str, threshold: float = DEFAULT_THRESHOLD) -> dict[str, Any]:
    with open(image_path, "rb") as image:
        response = requests.post(
            f"{BASE_URL}/api/v1/verify/",
            headers=_headers(),
            data={
                "collection_id": COLLECTION_ID,
                "external_id": external_id,
                "threshold": str(threshold),
            },
            files={"image": image},
            timeout=60,
        )
    return _check(response.json())

3. Usage in a view

# Django example
from verifai_client import VerifaiError, verify_person

def face_login(request):
    photo = request.FILES["image"]
    path = default_storage.save("tmp/" + photo.name, photo)
    try:
        data = verify_person(external_id=str(request.user.pk), image_path=path)
    except VerifaiError as exc:
        return JsonResponse({"error": exc.code}, status=422)
    finally:
        default_storage.delete(path)

    if data.get("matched"):
        return JsonResponse({"ok": True, "similarity": data["similarity"]})
    return JsonResponse({"ok": False}, status=401)