---
title: "Enroll a voice sample"
method: POST
path: "/v1/speakers/enroll"
tags: ["Speakers"]
---

# Enroll a voice sample

`POST /v1/speakers/enroll`

## Request

- Base URL: `https://platform.detectif.ai`
- URL: `https://platform.detectif.ai/v1/speakers/enroll`
- Auth: HTTP bearer

Saves a voice sample for a speaker so that later recordings can be verified against it. The speaker is created on first use. Send a recording of 15-60 seconds with at least 10 seconds of clear speech from that one person. Up to 5 samples per speaker; 2-3 samples from different sessions make verification more reliable. Main failures: too short, too long or too little speech (422, the message says what is needed), the speaker already has 5 samples (409), not enough credits (402). Requires scope `speakers:enroll`.

## Headers

- `Idempotency-Key` string, nullable: Optional (recommended) key that makes retries safe for 24 h: a retry with the same key and the same request returns the stored response without charging again.

## Response `200`

The sample was saved.

- EnrollResponse
  - `request_id` string, required
  - `operation_id` string, required
  - `object` 'speaker.enrollment', required
  - `speaker` Speaker, required
    - `speaker_id` string, required
    - `display_name` string, nullable, required
    - `samples` integer, required: Active enrollment samples for the current speaker model (max 5).
    - `created_at` string, required
    - `updated_at` string, required
  - `quality` EnrollQuality, required
    - `speech_seconds` number, required
    - `duration_seconds` number, required
  - `model` ModelInfo, required
    - `name` string, required: Model family: `aletheia` (deepfake detection) or `eidos` (speaker verification).
    - `version` string, required: Opaque model version; it changes whenever the model is updated.
  - `credits` CreditsCharged, required
    - `charged` integer, required: 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`.
    - `balance` integer, nullable, required: Your available credits after this request; null on the unlimited plan.
    - `original_charge` integer, nullable: Only on repeated requests (`charged` is then 0): the credits the original request used.
    - `unlimited` boolean, nullable: Present (true) only for accounts on the unlimited plan, where checks use no credits.
  - `latency_ms` number, required
  - `idempotent_replay` boolean, required

## Other responses

- `400`: The request is invalid, for example a missing or malformed field.
- `401`: The API key is missing, invalid or revoked.
- `402`: Not enough credits are available for this operation.
- `403`: The key lacks the required scope, the email address is not verified, or the account is suspended.
- `408`: The upload did not arrive in time (the whole file within 120 seconds, at least 64 KB per second).
- `409`: Conflict, for example a request with the same Idempotency-Key is still running, or the speaker already has the maximum number of samples.
- `413`: The upload is larger than 100 MB.
- `415`: Not a supported audio format, or the request is not multipart/form-data.
- `422`: The audio cannot be used (damaged, too short, too long, silent or too little speech; the message says what is needed), or the Idempotency-Key was already used for a different request.
- `429`: Too many requests or too many operations at the same time. Wait for the number of seconds in Retry-After.
- `500`: Something went wrong on our side. No credits were used.
- `502`: The check failed on our side. No credits were used; retry later.
- `503`: The service is busy, for example with many large uploads. Retry after the Retry-After seconds.
- `504`: The check took too long. No credits were used; retry later.

---

[API](https://skmtc.dev/detectif/apis/detectifai-developer-api.md) · [All operations](https://skmtc.dev/detectif/apis/detectifai-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/detectif/apis/detectifai-developer-api/revisions/24295482ed77?raw)