> ## Documentation Index
> Fetch the complete documentation index at: https://developers.mihu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Reference voiceprints

> Follow a stored person from the first second

Off by default and only for the requests that ask for it. Store the voice of the person you want to follow once (e.g.
the account holder, with their consent), then name it on a request with `reference_voiceprint=<id>`. Without a
reference, `speaker_lock`, `voice_isolation` and `diarize` take the **first** voice they hear as `S1`; with one, `S1`
is the stored person from the start, so a call where someone else speaks first, or a background voice that is louder
at the start, is still locked to the right person.

## Create: `POST /v1/voiceprints`

```bash theme={null}
curl https://stt.eu.mihu.ai/v1/voiceprints -H "Authorization: Bearer $KEY" \
  -F file=@customer-1042.wav -F name="Customer 1042" -F consent=true -F consent_reference=CRM-CONSENT-88123
```

| Field | Meaning |
| - | - |
| `file` or `file_url` | 3–120 s of **one** person speaking (any common format). At least 3 s of speech after silence is removed; **15–20 s of speech recommended** (10 s works, but verification errors are 30–50 % higher) |
| `name` | Your label, 1–100 characters |
| `consent` | Must be `true`: you confirm the person agreed to their voiceprint being stored and used. Without it → `400` |
| `consent_reference` | Optional (≤ 200 characters): your reference to the consent record (stored and returned as is) |
| `store` | `true` (default): we keep the voiceprint and answer its `id`. `false`: [we keep nothing](https://developers.mihu.ai/stt/voiceprints.md#not-stored-store-false) and answer a `token` |

```json theme={null}
{"id": "9b2f6c1e-3d4a-4f8b-a1c2-7e5d9f0b3a61", "object": "voiceprint", "name": "Customer 1042", "speech_seconds": 14.2,
 "created_at": 1793170800, "consent": {"given": true, "at": 1793170800, "reference": "CRM-CONSENT-88123"}}
```

* The voiceprint covers both channels: it is computed from the recording as sent and from the same speech through a
  simulated telephone line, so a voice recorded on a microphone or app is also recognised on a phone call.
* Only the speaker embedding (a list of numbers from which the audio cannot be rebuilt) is stored, with the name and
  the consent record. **The recording is not kept**: it is deleted as soon as the voiceprint is computed. Voiceprints
  are stored on the server that answers the API.
* Errors: `400` missing consent / name, longer than 120 s; `422` less than 3 s of speech, or more than one voice in the
  recording; `409` limit of 1 000 voiceprints per account reached.
* A voiceprint belongs to your account (API key's tenant); other accounts get `404`.

## List, read, delete

```bash theme={null}
curl https://stt.eu.mihu.ai/v1/voiceprints -H "Authorization: Bearer $KEY"          # {"object": "list", "data": [...]}
curl https://stt.eu.mihu.ai/v1/voiceprints/$ID -H "Authorization: Bearer $KEY"
curl -X DELETE https://stt.eu.mihu.ai/v1/voiceprints/$ID -H "Authorization: Bearer $KEY"   # {"id": ..., "deleted": true}
```

`DELETE` removes the voiceprint for good (use it when the person withdraws consent); requests that still name it get
`404`. The embedding itself is never returned. Voiceprint calls are not billed.

## Use: `reference_voiceprint`

```bash theme={null}
# file: only the stored person's speech becomes text, everyone else comes as "ignored"
curl https://stt.eu.mihu.ai/v1/audio/transcriptions -H "Authorization: Bearer $KEY" \
  -F file=@call.wav -F model=umay -F language=tr -F speaker_lock=true -F voice_isolation=true \
  -F reference_voiceprint=9b2f6c1e-3d4a-4f8b-a1c2-7e5d9f0b3a61
```

```
wss://stt.eu.mihu.ai/v1/stream?model=umay-stream&language=tr&api_key=<KEY>&voice_isolation=true&speaker_lock=true&reference_voiceprint=9b2f6c1e-…
```

* Works on files (sync and asynchronous; also in `extra_body` with OpenAI model names), `/v1/stream` (query) and
  `/v1/realtime` (query or session field `reference_voiceprint`).
* Needs `voice_isolation`, `speaker_lock` or `diarize` (else `400`). Unknown or deleted id → `404` (live: close `4400`).
* `voice_isolation` + reference: the isolation model follows the stored person from the first second; it still
  switches on only when another voice is heard. `diarize` + reference: `S1` = the stored person, others `S2`, `S3`, ….
* After an update of the voice model a voiceprint may answer `409` ("create it again"); this is announced in the
  changelog.

## Not stored: `store=false`

With `store=false` nothing is kept on our side. The answer carries a `token` instead of an `id`: the voiceprint,
encrypted and authenticated with a server key (AES-256-GCM) and bound to your account. You keep it (e.g. in your CRM
next to the customer) and send it wherever an id is accepted: `reference_voiceprint=<token>` and
`POST /v1/voiceprints/verify` with `voiceprint=<token>`.

```json theme={null}
{"id": null, "object": "voiceprint", "stored": false, "token": "vpt1.3fa1c2d9.Qm9vb…", "name": "Customer 1042",
 "speech_seconds": 14.2, "created_at": 1793170800, "account": "7d1e…", "consent": {"given": true, …}}
```

* The token cannot be read or changed by anyone (a changed token, or one of another account → `404`). It is still a
  derivative of a person's voice: store it like other personal data, delete it when consent is withdrawn (that is the
  deletion — there is nothing on our side).
* It does not show in `GET /v1/voiceprints` and does not count against the 1 000 limit. It stays valid until the voice
  model changes (then `409`, create it again; announced in the changelog).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.