Skip to content

Speaker Services - Voice Prints

Voice prints are immutable biometric evidence generated automatically during verification. Clients enroll a speaker, then submit verification requests.

Each verification first resolves its requested embedding model, or the current default. It reuses a completed snapshot only when the model version and all current usable enrollments match. Otherwise it rebuilds the embeddings and voice print synchronously and stores the complete evidence together. Changing a model or its default takes effect on subsequent requests. Historical verifications keep their original voice-print references.

Base path: /api/v1/speaker-services/speaker-verification

Method Endpoint relative to base Scope Description
GET /voice-prints speaker:voiceprints:read List retained evidence.
GET /voice-prints/{voicePrintId} speaker:voiceprints:read Read one evidence snapshot.
POST /speakers/{speakerId}/voice-prints/preview speaker:voiceprints:read Preview quality without persisting embeddings or a voice print.
DELETE /voice-prints/{voicePrintId} speaker:voiceprints:delete Exclude a snapshot from reuse; optional purge=true removes biometric artifacts immediately.
POST /voice-prints/{voicePrintId}/purge speaker:voiceprints:delete Purge an already deleted snapshot.

List Voice Prints

Optional filters: speakerId, model (model recorded at generation), resolvedModel, status, and isDeleted (default false). Pagination uses page=0, size=20 (maximum 100), and sort=createdAt,desc. Allowed sort fields are createdAt, completedAt, qualityScore, and status.

The response contains voicePrints, size, total, filters, and sort. The modelAlias on a voice print records the model used to generate it. Read the verification's own modelAlias for that request's selection.

Preview Voice Print Quality

POST /speakers/{speakerId}/voice-prints/preview accepts an optional body:

{"model": "speaker-default"}

Omit model to resolve the current default. Preview evaluates all current usable enrollments and discards its extracted vectors after returning quality results. It is an optional diagnostic, available even before the speaker meets the configured minimum for verification.

The response includes enrollmentCount, embeddingCount, qualityScore, qualityLevel, minSimilarity, maxSimilarity, outlierEnrollmentIds, and recommendation. Recommendations are ADD_MORE_ENROLLMENTS, REMOVE_OUTLIERS, and READY_FOR_VERIFICATION. Delete an outlier enrollment to exclude it from subsequent verification evidence.

Preview uses the dedicated speakerVoicePrintPreviews rate limit. No usable retained recordings returns 409 Conflict. Model authorization and model availability rules match verification.

Evidence Response

Field Type Description
id, speakerId UUID Evidence and owning speaker identifiers.
status string New completed evidence is READY; legacy FAILED records remain readable.
modelAlias string, nullable Effective model when this snapshot was generated.
resolvedModel, modelHash string, nullable Model version and vector-space hash; immutable after generation.
quality object, nullable score and level for this snapshot.
sourceEnrollments array, nullable Actual {enrollmentId, embeddingId} associations. Multiple segments produce multiple entries for one enrollment. An unavailable legacy association has embeddingId: null.
sourceEnrollmentCount integer Number of distinct source enrollments.
errorCode, errors nullable Historical build-failure information. New generation failures are retained as failed verifications without partial evidence.
isDeleted, isPurged boolean Evidence retention state.
createdAt, completedAt timestamp Generation timestamps.
deletedAt, purgedAt, purgeAt timestamp, nullable Retention timestamps.

Delete and Purge

Deletion excludes evidence from reuse. A later verification may generate a replacement from the speaker's usable recordings. To stop verification, disable or archive the speaker.

Automatic cleanup preserves snapshots and source embeddings while an unpurged verification references them. Unreferenced evidence follows the unused-evidence retention policy. Explicit purge overrides that protection and removes biometric artifacts while preserving minimal metadata and verification references.

Verification and overall biometric storage limits apply. Evidence storage includes retained embeddings and voice prints.