> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spoofsense.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SpoofSense Quickstart: Liveness Check in 5 Minutes

> Make your first face liveness API call with SpoofSense. Get an API key, POST an image, and get a calibrated real/spoof decision back in seconds.

This guide walks you through making your first liveness check and deepfake check with SpoofSense. In four steps you'll create an account, obtain an API key, call the detection endpoint with a real image, and understand every field in the response. By the end you'll also know how to switch to deepfake-only or unified detection with a single URL change.

<Steps>
  <Step title="Get an API Key">
    Sign in at [app.spoofsense.ai](https://app.spoofsense.ai) and create a key under **Dashboard → API keys**. Keys look like `sk_live_…` and are shown **once** — SpoofSense stores only a hash, so copy your key before closing the dialog.

    Export it as an environment variable so the examples below work without modification:

    ```bash theme={null}
    export SPOOFSENSE_API_KEY="sk_live_..."
    ```

    <Warning>
      The secret key must only ever live on your server. Never ship it in a browser bundle, a mobile app binary, or a public repository — doing so allows anyone who finds it to consume your credits.
    </Warning>
  </Step>

  <Step title="Run a Liveness Check">
    Send any face image to the liveness endpoint — as a multipart file upload, a base64-encoded JSON body, or a publicly accessible URL. The examples below use a multipart file upload, which is the simplest approach for server-side code.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://api.spoofsense.ai/v1/liveness_detection \
        -H "Authorization: Bearer $SPOOFSENSE_API_KEY" \
        -F "file=@selfie.jpg"
      ```

      ```javascript Node.js theme={null}
      import fs from "node:fs";

      const form = new FormData();
      form.append("file", new Blob([fs.readFileSync("selfie.jpg")]), "selfie.jpg");

      const res = await fetch("https://api.spoofsense.ai/v1/liveness_detection", {
        method: "POST",
        headers: { Authorization: `Bearer ${process.env.SPOOFSENSE_API_KEY}` },
        body: form,
      });
      console.log(await res.json());
      ```

      ```python Python theme={null}
      import os, requests

      res = requests.post(
          "https://api.spoofsense.ai/v1/liveness_detection",
          headers={"Authorization": f"Bearer {os.environ['SPOOFSENSE_API_KEY']}"},
          files={"file": open("selfie.jpg", "rb")},
      )
      print(res.json())
      ```
    </CodeGroup>
  </Step>

  <Step title="Read the Decision">
    A successful request returns a JSON object like this:

    ```json Response theme={null}
    {
      "product": "face_liveness",
      "decision": "real",
      "genuine_score": 0.9333,
      "threshold": 0.5,
      "spoof_type": null,
      "latency_ms": 190,
      "credits_remaining": 1240,
      "session_id": "d2f8…",
      "request_id": "9b1c…"
    }
    ```

    Act on `decision` — it is either `"real"` or `"spoof"` and is the field your application logic should branch on. The remaining fields support tuning and audit:

    * **`genuine_score`** — the raw calibrated probability (0–1) that the face is genuine. Higher means more confident the image is real.
    * **`threshold`** — the value currently applied to produce the decision (`genuine_score > threshold`). The default is `0.5`.
    * **`spoof_type`** — populated when `decision` is `"spoof"`, describing the attack category detected (e.g. `"printed_photo"`). `null` when the check passes.
    * **`latency_ms`** — server-side processing time in milliseconds.
    * **`credits_remaining`** — how many detection credits remain on your account after this call.
    * **`session_id`** / **`request_id`** — use these when contacting support or correlating logs.

    <Tip>
      Use `genuine_score` and `threshold` together when you want to tune your acceptance rate. Raising the threshold makes the check stricter; lowering it makes it more permissive. See [Thresholds & scores](/guides/thresholds) for a full guide.
    </Tip>
  </Step>

  <Step title="Try Deepfake or Unified Detection">
    The request shape is identical — only the endpoint changes. To check for AI-generated or face-swapped imagery, call `/v1/deepfake_detection`. To run both liveness and deepfake checks in a single round trip, call `/v1/unified_detection`:

    ```bash theme={null}
    curl -X POST https://api.spoofsense.ai/v1/unified_detection \
      -H "Authorization: Bearer $SPOOFSENSE_API_KEY" \
      -F "file=@selfie.jpg"
    ```

    `/v1/unified_detection` runs both checks and returns `decision: "real"` only when **every** check passes. The response also includes a per-product `checks` object so you can see which individual check failed and by how much.
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Verify Live Users with SDKs" icon="mobile-screen-button" href="/verification-sessions/overview">
    For onboarding or KYC flows, use our Web and Android SDKs to capture the selfie directly from the camera with injection-attack protection — no image upload code required on your end.
  </Card>

  <Card title="Tune Thresholds" icon="sliders" href="/guides/thresholds">
    Learn how to raise or lower the decision threshold to balance your false-accept and false-reject rates for your specific risk tolerance.
  </Card>

  <Card title="Authentication Guide" icon="key" href="/guides/authentication">
    Everything about API key scopes, rotation, and best practices for keeping your credentials secure.
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference">
    Every endpoint, parameter, and response field — with an interactive try-it console.
  </Card>
</CardGroup>