Quickstart

This guide takes you from a new account to your first model requests. Every request goes to the base URL https://platform.detectif.ai/v1 and is authenticated with an API key.

The examples use three clients. Pick one:

cURL, from any shell.
Python with requests (pip install requests).
JavaScript with the built-in fetch, FormData and Blob in Node.js 18 or later. Save the snippets as .mjs files so top-level await works.

1. Create an account and verify your email

Sign up at platform.detectif.ai and verify your email address. The first time you sign in with a verified email, your account receives a one-time grant of 100,000 credits. Each successful model operation costs 50 credits. See Credits and billing.

2. Create an API key

In the dashboard, open API keys, select Create key, name it and choose its scopes. The full key (dtf_live_...) is shown once. Store it in a secret manager or an environment variable, never in source code:

Example (shell)

export DETECTIF_API_KEY="dtf_live_..."

For this guide, give the key the scopes credits:read, deepfake:detect, speakers:enroll and speakers:verify. See Authentication and API keys for the full scope list.

3. Check your balance (free)

Reading your balance costs nothing and confirms that the key works.

Example (cURL)

curl https://platform.detectif.ai/v1/credits \
  -H "Authorization: Bearer $DETECTIF_API_KEY"

Example (Python)

import os
import requests

resp = requests.get(
    "https://platform.detectif.ai/v1/credits",
    headers={"Authorization": f"Bearer {os.environ['DETECTIF_API_KEY']}"},
    timeout=30,
)
print(resp.status_code, resp.json())

Example (Node.js)

const res = await fetch("https://platform.detectif.ai/v1/credits", {
  headers: { Authorization: `Bearer ${process.env.DETECTIF_API_KEY}` },
});
console.log(res.status, await res.json());

A 401 response means the key is missing, mistyped or revoked. See Errors.

4. Check a recording for synthetic speech (50 credits)

Send an audio file (0.5 to 120 seconds, up to 20 MB) as the multipart field file. The Idempotency-Key header makes the request safe to retry; see Idempotency and retries. The cURL examples create keys with uuidgen, which ships with macOS and most Linux distributions; any unique string works.

Example (cURL)

curl https://platform.detectif.ai/v1/deepfake/detect \
  -H "Authorization: Bearer $DETECTIF_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@sample.wav"

Example (Python)

import os
import uuid
import requests

with open("sample.wav", "rb") as f:
    resp = requests.post(
        "https://platform.detectif.ai/v1/deepfake/detect",
        headers={
            "Authorization": f"Bearer {os.environ['DETECTIF_API_KEY']}",
            "Idempotency-Key": str(uuid.uuid4()),
        },
        files={"file": ("sample.wav", f, "audio/wav")},
        timeout=120,
    )
body = resp.json()
if not resp.ok:
    raise SystemExit(f"{body['error']['code']}: {body['error']['message']} ({body['request_id']})")
result = body["result"]
print(result["label"], result["score"], result["threshold"])

Example (Node.js)

import { readFile } from "node:fs/promises";
import { randomUUID } from "node:crypto";

const form = new FormData();
form.append("file", new Blob([await readFile("sample.wav")], { type: "audio/wav" }), "sample.wav");

const res = await fetch("https://platform.detectif.ai/v1/deepfake/detect", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DETECTIF_API_KEY}`,
    "Idempotency-Key": randomUUID(),
  },
  body: form,
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message} (${body.request_id})`);
console.log(body.result.label, body.result.score, body.result.threshold);

Example response (values are illustrative):

Example (JSON)

{
  "request_id": "req_8f3a1c2d9e4b34c08676aa1b",
  "operation_id": "op_5b7e0a91c3d2269cf8f9690e4859514c",
  "object": "deepfake.detection",
  "result": {
    "label": "genuine",
    "is_synthetic": false,
    "score": 0.08,
    "threshold": 0.62,
    "score_semantics": "model output probability of synthetic speech; not calibrated to your traffic",
    "duration_seconds": 7.4,
    "segments": [
      { "start": 0.0, "end": 4.0, "score": 0.07 },
      { "start": 2.0, "end": 6.0, "score": 0.09 },
      { "start": 4.0, "end": 7.4, "score": 0.08 }
    ]
  },
  "model": { "name": "aletheia-wavlm", "version": "wavlm-finetune-n-m43-moredata-ep063" },
  "credits": { "charged": 50, "balance": 99950 },
  "latency_ms": 412.6,
  "idempotent_replay": false
}

The score is the model's output for this recording. It is not proof that a voice is genuine or synthetic. The default threshold was fitted on English speech; results for other languages are less reliable. See Deepfake detection for how to read it.

5. Enroll and verify a speaker (50 credits each)

Enroll a speaker with one recording of 5 to 60 seconds (10 seconds or more of clean speech is recommended), then verify with a recording of 3 to 60 seconds. speaker_id is your own identifier.

Example (cURL)

curl https://platform.detectif.ai/v1/speakers/enroll \
  -H "Authorization: Bearer $DETECTIF_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "speaker_id=customer-1042" \
  -F "file=@enrollment.wav"

curl https://platform.detectif.ai/v1/speakers/verify \
  -H "Authorization: Bearer $DETECTIF_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "speaker_id=customer-1042" \
  -F "file=@caller.wav"

Example (Python)

import os
import uuid
import requests

API = "https://platform.detectif.ai/v1"
AUTH = {"Authorization": f"Bearer {os.environ['DETECTIF_API_KEY']}"}

def post_audio(path, endpoint, fields):
    with open(path, "rb") as f:
        resp = requests.post(
            f"{API}/{endpoint}",
            headers={**AUTH, "Idempotency-Key": str(uuid.uuid4())},
            data=fields,
            files={"file": (os.path.basename(path), f)},
            timeout=120,
        )
    body = resp.json()
    if not resp.ok:
        raise RuntimeError(f"{body['error']['code']}: {body['error']['message']} ({body['request_id']})")
    return body

post_audio("enrollment.wav", "speakers/enroll", {"speaker_id": "customer-1042"})
verification = post_audio("caller.wav", "speakers/verify", {"speaker_id": "customer-1042"})
print(verification["result"])

Example (Node.js)

import { readFile } from "node:fs/promises";
import { basename } from "node:path";
import { randomUUID } from "node:crypto";

const API = "https://platform.detectif.ai/v1";

async function postAudio(path, endpoint, fields) {
  const form = new FormData();
  for (const [key, value] of Object.entries(fields)) form.append(key, value);
  form.append("file", new Blob([await readFile(path)]), basename(path));
  const res = await fetch(`${API}/${endpoint}`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.DETECTIF_API_KEY}`,
      "Idempotency-Key": randomUUID(),
    },
    body: form,
  });
  const body = await res.json();
  if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message} (${body.request_id})`);
  return body;
}

await postAudio("enrollment.wav", "speakers/enroll", { speaker_id: "customer-1042" });
const verification = await postAudio("caller.wav", "speakers/verify", { speaker_id: "customer-1042" });
console.log(verification.result);

result.similarity is a cosine similarity between voice embeddings, not a probability. Verification is less reliable on 8 kHz or codec-compressed phone-call audio. See Speaker enrollment and verification.

Next steps

Authentication and API keys: scopes, rotation and revocation.
Credits and billing: what is charged and what is free.
Idempotency and retries: retry without paying twice.
Errors: the error envelope and every error code.
Rate limits and audio limits.
Data retention and privacy.
MCP server: use the API from MCP clients such as Claude Code.
The machine-readable OpenAPI description is at /v1/openapi.json.

Quickstart

#1. Create an account and verify your email

#2. Create an API key

#3. Check your balance (free)

#4. Check a recording for synthetic speech (50 credits)

#5. Enroll and verify a speaker (50 credits each)

#Next steps

1. Create an account and verify your email

2. Create an API key

3. Check your balance (free)

4. Check a recording for synthetic speech (50 credits)

5. Enroll and verify a speaker (50 credits each)

Next steps