Installation

Install the Circadify Python SDK to capture vitals from a webcam, video, or frames, or run the headless REST and tensor path.

The Circadify Python SDK is a full client SDK and a peer to the Web, iOS, and Android SDKs. It captures from a webcam, a video file, or your own frames, runs MediaPipe face detection and ROI extraction on-device, and ships only a cropped 12-channel tensor to the server for GPU inference — raw video never leaves the device. It also exposes a core REST and tensor path for headless, server, and batch use, plus an optional camera / face-glow overlay (render_face_glow) you can drop into your own UI.

Before you start

You need two separate credentials from Circadify, each with a different job:

1. A Circadify access token — authenticates the install of the circadify package from Circadify's private package index. This is the same access token that installs the Web, iOS, and Android SDKs.
2. An API key (ck_live_ or ck_test_) — authenticates the SDK at runtime when it takes measurements. Covered under Get an API Key below.

The access token gets you the package; the API key runs it.

Install

circadify is distributed from Circadify's private package index using your Circadify access token — the same token and host as the other SDKs. The recommended, lowest-leak setup is a ~/.netrc entry, which pip reads natively, so the token never lands in a command, pip.conf, logs, or shell history (the same hygiene as the iOS git credential):

machine sdk.circadify.com
  login <your-developer-account-email>
  password <your-circadify-access-token>

chmod 600 ~/.netrc   # keep it private; never commit it

Confirm your account has Python access before installing — "rolling out" means it may not be enabled yet, and a not-yet-published package and a missing token both return the same 401. Probe the index directly (no install, no quota):

curl --netrc -sS -o /dev/null -w '%{http_code}\n' https://sdk.circadify.com/pypi/simple/circadify/

# Skip if you already have a project/virtual environment activated.
python3 -m venv .venv && source .venv/bin/activate

Then install — note there is no credential in the index URL; pip, poetry, and uv all read it from ~/.netrc:

pip install --no-input --extra-index-url https://sdk.circadify.com/pypi/simple/ "circadify[camera]"

export PIP_EXTRA_INDEX_URL="https://${CIRCADIFY_INDEX_USER}:${CIRCADIFY_INDEX_TOKEN}@sdk.circadify.com/pypi/simple/"
pip install "circadify[camera]"

Choose an install: core vs. camera

The package has two install shapes. Pick based on what you capture from:

# Core — REST wire protocol + tensor path. Deps: requests + numpy only.
# Runs scan_tensor() and the raw REST methods (incl. the free sandbox) with NO camera.
pip install circadify
 
# Camera extra — adds opencv-python + mediapipe.
# REQUIRED for measure_vitals / measure_from_video / measure_from_frames AND circadify.ui.
pip install "circadify[camera]"

If you call a capture method without the [camera] extra installed, the SDK raises MissingDependencyError.

Declare it in pyproject.toml

Pin a compatible release so a future minor doesn't surprise your build:

[project]
dependencies = [
    # Core only:
    "circadify>=0.1,<0.2",
    # Or, for webcam / video / frame capture and the UI:
    # "circadify[camera]>=0.1,<0.2",
]

Requirements

Get an API Key

This is the second credential from Before you start, and it is separate from the access token used to install the package. The access token authenticates the install; an API key authenticates the SDK at runtime when it takes measurements.

Get an API key from the Keys page in the developer portal. Keys come in two formats, distinguished by their prefix: ck_live_ (production — real measurements, metered against your plan; POST /sdk/session/start consumes 1 scan on session start) and ck_test_ (sandbox — deterministic synthetic vitals, zero quota, never billed). Pass it to CircadifyClient(api_key=...) and read it from an environment variable rather than hardcoding it. See Authentication for key details.

Verify Installation

Construct a client with your sandbox key (ck_test_, zero quota) read from the environment and confirm the import resolves:

import os
 
from circadify import CircadifyClient
 
# Never hardcode a key — read it from the environment.
client = CircadifyClient(api_key=os.environ["CIRCADIFY_API_KEY"])  # ck_test_your_key_here
 
print("circadify ready —", client.key_environment, "environment")  # -> "test"
client.close()

If this prints circadify ready — test environment without raising, the core install works. To verify the capture extra, confirm import cv2 and import mediapipe both succeed after installing circadify[camera].

Next Steps

• Quickstart — Capture your first measurement in five lines
• Configuration — Constructor options, callbacks, and fallback behavior
• Face-Glow Overlay — render_face_glow, themes, and building your own scan UI
• Camera & Input — Webcam, video, frames, and the tensor path