Enroll a voice sample

POST/v1/speakers/enroll

#Authentication

#Headers

#Request body

Send the request as multipart/form-data. Upload the audio file in the file field (up to 100 MB) and send the other fields as form fields. See Audio and limits.

• filefilerequired

  The audio file: WAV, MP3, FLAC, OGG/Opus, WebM, M4A/AAC or AIFF, at most 100 MB.

• speaker_idstringrequired

  Your identifier for the speaker (1-64 characters: letters, digits, _ . : -).

  1 to 64 characterspattern ^[A-Za-z0-9_.:-]{1,64}$

• display_namestring

  Optional label for the speaker, shown in the dashboard.

  at most 128 characters

#Response

200 The sample was saved.

• request_idstringrequired
• operation_idstringrequired
• objectstringrequired

  always "speaker.enrollment"

• speakerobjectrequired
  5 fields in speaker

  • speaker_idstringrequired

    pattern ^[A-Za-z0-9_.:-]{1,64}$

  • display_namestring or nullrequired
  • samplesintegerrequired

    Active enrollment samples for the current speaker model (max 5).

  • created_atstringrequired
  • updated_atstringrequired
• qualityobjectrequired
  2 fields in quality

  • speech_secondsnumberrequired
  • duration_secondsnumberrequired
• modelobjectrequired
  2 fields in model

  • namestringrequired

    Model family: aletheia (deepfake detection) or eidos (speaker verification).

  • versionstringrequired

    Opaque model version; it changes whenever the model is updated.

• creditsobjectrequired
  4 fields in credits

  • chargedintegerrequired

    Credits used by this request. A repeated request with the same Idempotency-Key uses none: it reports 0 here and what the original request used in original_charge.

  • balanceinteger or nullrequired

    Your available credits after this request; null on the unlimited plan.

  • original_chargeinteger or null

    Only on repeated requests (charged is then 0): the credits the original request used.

  • unlimitedboolean or null

    Present (true) only for accounts on the unlimited plan, where checks use no credits.

• latency_msnumberrequired
• idempotent_replaybooleanrequired

#Example response

{
  "request_id": "req_8f14e45fceea167a5a36dedd",
  "operation_id": "op_6f1ed002ab5595859014ebf0951522d9",
  "object": "speaker.enrollment",
  "speaker": {
    "speaker_id": "customer-4711",
    "display_name": "Ada Lovelace",
    "samples": 1,
    "created_at": "2026-10-13T09:30:00Z",
    "updated_at": "2026-10-13T09:30:00Z"
  },
  "quality": {
    "speech_seconds": 17.9,
    "duration_seconds": 19.2
  },
  "idempotent_replay": false
}

#Errors

Error bodies share one shape with a stable error.code; see Errors for every code and how to fix it.

#Code samples

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

import os
import uuid

import requests

with open("clip.wav", "rb") as f:
    resp = requests.post(
        "https://platform.detectif.ai/v1/speakers/enroll",
        headers={"Authorization": f"Bearer {os.environ['DETECTIF_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
        data={"speaker_id": "alice"},
        files={"file": f},
        timeout=300,
    )
print(resp.status_code, resp.json())

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

const form = new FormData();
form.append("speaker_id", "alice");
form.append("file", new Blob([await readFile("clip.wav")]), "clip.wav");

const res = await fetch("https://platform.detectif.ai/v1/speakers/enroll", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DETECTIF_API_KEY}`,
    "Idempotency-Key": randomUUID(),
  },
  body: form,
});
console.log(res.status, await res.json());