How to use the API

This doc shows how to integrate our voice deepfake detection into your apps. Use the hosted API with an API key (in progress) so you don’t need to run anything locally or on a VPS—or self-host for full control.

Try Detect (web UI)Self-host (optional)

Hosted API & API keys (in progress)

We provide API keys and a hosted endpoint so you can integrate our service into your apps without hosting locally or on a VPS.

A hosted API and endpoint are currently in progress. Once live, you’ll get a base URL and an API key: send audio to our endpoint with your key and receive the detection result. No server to run, no model to download—just call the API from your app. We’ll update this doc and notify when the endpoint and key signup are available. Until then, you can use the Detect page or self-host (see Self-hosting).

API playground (in progress)

We are also building an in-browser playground to try the API and test your API key. Docs will be updated when it’s ready.

Overview

The API exposes two endpoints: GET /api/health (or /health on the hosted endpoint) for status, and POST /api/predict (or /predict) for sending an audio file and receiving a probability and label (real/fake). The same request/response format applies whether you use the hosted API or your own deployment.

Quick start

When running locally, the Next.js app proxies /api/health and /api/predict to the Flask backend. Ensure the backend is running (see Get started).

Base URL

Hosted API (in progress): we’ll give you a single base URL (e.g. https://api.example.com) for all requests. Use it from any app—no server of your own. Self-hosted: your own Next.js or backend URL (e.g. same origin or BACKEND_URL). The hosted base URL will be published when the endpoint is live.

Authentication (API keys)

Hosted API (in progress): we provide API keys. Send your key in the request (e.g. Authorization: Bearer YOUR_API_KEY or a header like X-API-Key: YOUR_API_KEY). Key signup and exact header will be documented when the endpoint is ready. Self-hosted: no API key required.

Endpoints

GET /api/health

Returns backend status, whether the model is loaded, device, and optional error message.

Response (200)

{ "status", "model_loaded?", "model_error?", "device?", "best_model?" }

POST /api/predict

Send a multipart form with audio (file). Returns P(fake) and label, or an error object.

Success (200)

{ "probability": number, "label": "real" | "fake" }

Error (4xx/5xx)

{ "error": string, "details"?: string }

Request & response schemas

POST /api/predict: Content-Type: multipart/form-data. Body: audio (file). Supported formats depend on the backend (e.g. WAV, MP3, FLAC).

Code examples

Use the hosted base URL and your API key when the endpoint is live. For self-hosted, use your own URL and omit the auth header.

curl (hosted API — use your key when live)

# Health
curl -X GET https://vprd.cps-ai.com/health \
  -H "Authorization: Bearer YOUR_API_KEY"

# Predict
curl -X POST https://vprd.cps-ai.com/predict \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "audio=@clip.wav"

JavaScript (fetch)

const form = new FormData();
form.set("audio", fileInput.files[0]);
const res = await fetch("https://vprd.cps-ai.com/predict", {
  method: "POST",
  headers: { "Authorization": "Bearer YOUR_API_KEY" },
  body: form,
});
const data = await res.json(); // { probability, label }

Error handling

On failure the API returns a JSON object with error and optional details. Common cases: missing audio field (400), model not loaded (500), backend unreachable (502).

Self-hosting

If you prefer to run the stack yourself (locally or on a VPS), the project is open source. You get the same API without using our hosted endpoint or an API key. See Get started for local setup and Deployment for hosting on a VPS.

Get started Deployment Mission