Quickstart

Get your API key

Register for API access and select a plan. Once approved, log in to your dashboard and click Generate API Key. You will receive two credentials:

API Key:    cf_live_xxxxxxxxxxxxxxxxxxxxxxxx
API Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxCopy

Set up the signature helper

Every request must be signed with HMAC-SHA256. Copy the helper for your language:

import hmac, hashlib, time, json, requests

API_KEY    = "cf_live_your_key"
API_SECRET = "your_secret"
BASE_URL   = "https://vision.cloudface-ai.com"

def cf(method, path, body=None):
    ts  = str(int(time.time()))
    bb  = json.dumps(body).encode() if body else b""
    sig = hmac.new(API_SECRET.encode(), ts.encode() + bb, hashlib.sha256).hexdigest()
    return requests.request(method, BASE_URL + path,
        headers={
            "X-CloudFace-Key"      : API_KEY,
            "X-CloudFace-Signature": sig,
            "X-CloudFace-Timestamp": ts,
            "Content-Type"         : "application/json"
        }, json=body)Copy

const crypto = require("crypto");
const axios  = require("axios");

const API_KEY    = "cf_live_your_key";
const API_SECRET = "your_secret";
const BASE_URL   = "https://vision.cloudface-ai.com";

function cf(method, path, body = null) {
  const ts  = String(Math.floor(Date.now() / 1000));
  const bb  = body ? JSON.stringify(body) : "";
  const sig = crypto.createHmac("sha256", API_SECRET)
                     .update(ts + bb).digest("hex");
  return axios({ method, url: BASE_URL + path, data: body,
    headers: {
      "X-CloudFace-Key"      : API_KEY,
      "X-CloudFace-Signature": sig,
      "X-CloudFace-Timestamp": ts,
      "Content-Type"         : "application/json"
    }
  });
}Copy

# Set your credentials
API_KEY="cf_live_your_key"
API_SECRET="your_secret"

# Generate signature
TIMESTAMP=$(date +%s)
BODY='{"name":"My Event"}'
SIGNATURE=$(echo -n "${TIMESTAMP}${BODY}" | openssl dgst -sha256 -hmac "$API_SECRET" | awk '{print $2}')

curl -X POST https://vision.cloudface-ai.com/v1/events \
  -H "X-CloudFace-Key: $API_KEY" \
  -H "X-CloudFace-Signature: $SIGNATURE" \
  -H "X-CloudFace-Timestamp: $TIMESTAMP" \
  -H "Content-Type: application/json" \
  -d "$BODY"Copy

Create an event

An event is a named index namespace for a set of photos — a wedding, conference, sports event, etc.

resp     = cf("POST", "/v1/events", {"name": "My First Event"})
event_id = resp.json()["event_id"]
print(event_id)  # e.g. "a3f9b2c1-d4e5"Copy

Index your photos

Submit an array of publicly accessible photo URLs. Processing happens in the background — up to 500 URLs per request.

cf("POST", f"/v1/events/{event_id}/index", {
    "photos": [
        "https://your-storage.com/photo1.jpg",
        "https://your-storage.com/photo2.jpg",
    ]
})Copy

Wait for indexing to complete

Poll the status endpoint until status returns "ready".

import time

while True:
    s = cf("GET", f"/v1/events/{event_id}/status").json()
    print(f"Status: {s['status']} | Photos: {s['photo_count']} | Faces: {s['face_count']}")
    if s["status"] == "ready" and s["photo_count"] > 0:
        break
    time.sleep(5)Copy

Search by selfie

Submit a selfie URL. Get back all matching photos with similarity scores. Use threshold to control sensitivity (0.5–0.9, default 0.7).

result = cf("POST", f"/v1/events/{event_id}/search", {
    "selfie_url": "https://your-storage.com/guest_selfie.jpg",
    "threshold" : 0.6
})

data = result.json()
print(f"Found {data['total_matches']} matching photos")

for match in data["matches"]:
    print(f"  Photo index {match['photo_index']} — {match['confidence']}")Copy