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

The Detect page is a live playground for the FastAPI backend. It uploads audio through /api/predict, saves results to your browser history, and shows the full meta-learning response in the "Raw response" panel.

Overview

The Next.js app exposes GET /api/health and POST /api/predict, which proxy to a FastAPI backend. The FastAPI service in fast-api-server/ exposes /health, /predict, /predict/url, and /predict/batch, returning a rich meta-learning response (per-chunk probabilities, votes, and a file-level verdict). The browser-facing /api/predict normalizes this into a simple probability + label and also exposes the full backend payload.

Quick start

When running locally, the Next.js app proxies /api/health and /api/predict to the FastAPI backend. Set BACKEND_URL to your FastAPI base URL (for example http://127.0.0.1:8000) and ensure the server is running (see Get started and fast-api-server README).

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). The frontend API normalizes the meta-learning backend response into P(fake) and label, and also returns the full FastAPI payload so you can inspect chunk-level details.

Success (200)

{ "probability": number, "label": "real" | "fake", "backend"?: PredictionResponse }

Error (4xx/5xx)

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

POST /api/predict/url (backend only)

Backend-only endpoint that downloads audio from a public URL and runs the same meta-learning pipeline. Use it from trusted server-side code (never expose it directly to untrusted browsers).

Request

POST /predict/url Content-Type: application/json

{ "url": string, "filename"?: string }

POST /api/predict/batch (backend only)

Backend-only batch endpoint that accepts multiple files in one request and returns an array of results. Useful for offline analysis or queued jobs.

Request

POST /predict/batch Content-Type: multipart/form-data

files[]: file, files[]: file, ... (max 20)

Backend response (meta-learning)

The FastAPI server uses a Prototypical Network over 3-second chunks. For each file it returns a rich JSON payload including a file-level verdict and per-chunk details. The browser wraps this in the backend field:

{
  "request_id": "uuid",
  "filename": "clip.wav",
  "processing_time_sec": 1.23,
  "verdict": "Real" | "Fake",
  "confidence": 0.85,
  "real_votes": 170,
  "fake_votes": 30,
  "total_chunks": 200,
  "real_vote_pct": 85.0,
  "fake_vote_pct": 15.0,
  "mean_prob_real": 0.812,
  "mean_prob_fake": 0.188,
  "chunk_details": [
    {
      "chunk_idx": 0,
      "chunk_start_sec": 0.0,
      "chunk_end_sec": 3.0,
      "label": "Real",
      "prob_real": 0.8931,
      "prob_fake": 0.1069
    },
    // ...
  ]
}

Request & response schemas

POST /api/predict: Content-Type: multipart/form-data. Body: audio (file). Supported formats depend on the backend (WAV, MP3, FLAC, OGG, AAC, M4A, MP4 up to 150 MB, enforced by the FastAPI server and Nginx).

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