Configuration

Configure the Circadify Python SDK with API keys, callbacks, capture options, and demographics.

Create one CircadifyClient per process or measurement flow. Only api_key is required — everything else has a sensible default. Never hardcode a key; read it from the environment.

Initialization

The minimal form takes only an API key:

import os
from circadify import CircadifyClient
 
client = CircadifyClient(api_key=os.environ["CIRCADIFY_API_KEY"])

For full control, pass any of the keyword-only options. All arguments after api_key are keyword-only:

import os
from circadify import CircadifyClient
 
client = CircadifyClient(
    api_key=os.environ["CIRCADIFY_API_KEY"],  # "ck_test_..." or "ck_live_..."
    base_url="https://api.circadify.com",
    timeout=30.0,
    poll_interval=2.0,
    poll_timeout=120.0,
    measurement_duration=20.0,
    allow_fallback_vitals=False,
    on_progress=lambda p: print(p.phase, p.percent),
    on_landmarks=None,
    on_quality=None,
    on_frame=None,
    model_asset_path=None,
    debug=False,
)

CircadifyClient is a context manager, so prefer with to release the camera and HTTP session deterministically:

with CircadifyClient(api_key=os.environ["CIRCADIFY_API_KEY"]) as client:
    result = client.measure_vitals()
    print(result.heart_rate, result.confidence)

A ck_test_* key targets the free sandbox (zero quota, deterministic synthetic vitals); a ck_live_* key is metered. Read client.key_environment ("test" or "live") to confirm. A malformed key raises InvalidApiKeyError; an empty key raises MissingApiKeyError.

Configuration reference

After any call, client.last_rate_limit holds a RateLimitInfo or None.

Quieting native logs

On import and during a scan, MediaPipe / TFLite / OpenGL emit C++ banner lines to the console (e.g. Created TensorFlow Lite XNNPACK delegate for CPU, a GL version … line, init-domain / fiber-init lines). These come from the native libraries, not the SDK's Python logger — so debug=False does not silence them. Set these environment variables before importing circadify (or cv2 / mediapipe), since the native libraries read them at load time:

import os
os.environ["GLOG_minloglevel"] = "2"      # MediaPipe / abseil C++ logs (0=info … 3=fatal)
os.environ["TF_CPP_MIN_LOG_LEVEL"] = "3"  # TFLite / XNNPACK delegate logs
 
from circadify import CircadifyClient  # import AFTER setting the vars above

Callbacks

Pass callbacks to drive a scan UI around the capture engine. All four are optional.

on_progress — ScanProgress

on_landmarks

Receives a list of (x, y) face-landmark pixel coordinates per frame. Use it to render a custom overlay.

on_quality — QualityState

on_frame — FrameEvent

Phase enum

Capture policy

The frame-rate target, minimum frame count, readiness gate, and watchdogs are fixed and tuned for measurement quality. They are not constructor options.

Demographics

Demographics are optional but can improve measurement accuracy when provided. Every measurement method accepts a Demographics, a plain dict, or None.

from circadify import Demographics, Sex
 
demographics = Demographics(age=35, sex=Sex.MALE, fitzpatrick=3)
result = client.measure_vitals(demographics=demographics)

You can also pass the dict form directly:

result = client.measure_vitals(
    demographics={"age": 35, "sex": "M", "fitzpatrick": 3},
)

Next Steps

• Methods — every measurement and REST method on CircadifyClient.
• Face-Glow Overlay — the optional render_face_glow camera/glow pipeline you compose your own UI around.
• Camera & Input — webcam, video file, and your-own-frames input modes.
• Error Handling — catch CircadifyError, inspect .code, and retry transient failures.