Skip to content

Speaker Services - Voice Prints

Manage speaker voice prints created from usable enrollments. Enrollments remain the source audio and quality records; voice prints are explicit biometric resources used for verification.

Base path: /api/v1/speaker-services

Method Endpoint Description
GET /api/v1/speaker-services/speaker-verification/voice-prints List Voice Prints
POST /api/v1/speaker-services/speaker-verification/speakers/{speakerId}/voice-prints Create Voice Print
POST /api/v1/speaker-services/speaker-verification/speakers/{speakerId}/voice-prints/preview Preview Voice Print Quality
GET /api/v1/speaker-services/speaker-verification/voice-prints/{voicePrintId} Get Voice Print
POST /api/v1/speaker-services/speaker-verification/voice-prints/{voicePrintId}/activate Activate Voice Print
POST /api/v1/speaker-services/speaker-verification/voice-prints/{voicePrintId}/set-default Set Default Voice Print
DELETE /api/v1/speaker-services/speaker-verification/voice-prints/{voicePrintId} Delete Voice Print
POST /api/v1/speaker-services/speaker-verification/voice-prints/{voicePrintId}/purge Purge Voice Print

Preview Voice Print Quality

POST /api/v1/speaker-services/speaker-verification/speakers/{speakerId}/voice-prints/preview

Requires Authentication - Scopes: speaker:voiceprints:read

Rate Limited - Uses speakerVoicePrintPreviews and global request limits

Estimate voice print quality from the speaker's enrollments without creating a voice print. The service resolves embeddings (extracting on-the-fly if needed and caching for future use), calls the centroid quality computation, and returns quality metrics with an actionable recommendation.

This endpoint is designed for iterative enrollment workflows: users can create enrollments, preview quality, and decide whether to add more enrollments, remove outliers, or proceed to build a voice print.

Path Parameters
Parameter Type Required Description
speakerId string (UUID) Yes Speaker whose enrollments to evaluate.
SpeakerServiceVoicePrintPreviewRequest
Field Type Required Default Description
model string No Tenant default alias Embedding model alias. See Embedding Models.
sourceEnrollmentIds string[] (UUID) No All usable READY enrollments Optional subset of ready enrollments to evaluate.
SpeakerServiceVoicePrintPreviewRequest
{
  "model": "speaker-default",
  "sourceEnrollmentIds": ["...", "..."]
}
SpeakerServiceVoicePrintPreviewResponse
Status Description
200 OK Quality preview computed successfully.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope.
404 Not Found Speaker or selected enrollment not found.
409 Conflict Speaker does not have any usable READY enrollments, model alias not configured, or model not available.
429 Too Many Requests Preview rate limit exceeded.

Iterative Enrollment Workflow

  1. Create enrollments (audio uploads) - each returns immediately with per-enrollment quality indicators.
  2. Call Preview Voice Print Quality to check cross-enrollment cohesion.
  3. If recommendation is ADD_MORE_ENROLLMENTS → add more enrollments and preview again.
  4. If recommendation is REMOVE_OUTLIERS → remove the identified outlier enrollments and preview again.
  5. If recommendation is READY_TO_BUILD → create the voice print.

List Voice Prints

GET /api/v1/speaker-services/speaker-verification/voice-prints

Requires Authentication - Scopes: speaker:voiceprints:read

Retrieve voice prints owned by the authenticated caller.

Query Parameters
Parameter Type Required Default Description
speakerId string (UUID) No - Filter by speaker.
model string No - Filter by requested model alias.
resolvedModel string No - Filter by concrete resolved model string.
status SpeakerVoicePrintStatus[] No - Filter by voice print status. Values: READY, FAILED.
isActive boolean No - Filter by active voice prints.
isDefault boolean No - Filter by speaker default voice prints.
isDeleted boolean No false Include or filter deleted voice prints.
sort string No createdAt,desc Sort field and direction. Allowed fields: createdAt, completedAt, qualityScore, status.
SpeakerServiceVoicePrintsListResponse
Field Type Nullable Description
voicePrints SpeakerServiceVoicePrintResponse[] No Array of voice prints.
size integer No Number of items returned.
total long No Total number of matching items.
filters object No Echo of applied filters.
sort object No Applied sort order.
Status Description
200 OK Voice prints retrieved successfully.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope.

Create Voice Print

POST /api/v1/speaker-services/speaker-verification/speakers/{speakerId}/voice-prints

Requires Authentication - Scopes: speaker:voiceprints:write

Rate Limited - Uses speakerVoicePrintCreations and global request limits

Create a voice print from the speaker's usable READY enrollments. Creation is synchronous: the response contains the terminal voice print status (READY or FAILED).

Path Parameters
Parameter Type Required Description
speakerId string (UUID) Yes Speaker that owns the voice print.
SpeakerServiceCreateVoicePrintRequest
Field Type Required Default Description
model string No Tenant default alias Embedding model alias. See Embedding Models.
sourceEnrollmentIds string[] (UUID) No All usable READY enrollments Optional subset of ready enrollments to use.
forceRebuild boolean No false Create a replacement even when an active voice print already exists for the same resolved model.
makeDefault boolean No false Make the new READY voice print the speaker default after successful creation.
reason string No - Optional audit/debug reason.
SpeakerServiceCreateVoicePrintRequest
{
  "model": "speaker-default",
  "forceRebuild": false,
  "makeDefault": true,
  "reason": "new default model rollout"
}

Existing Active Voice Print

If an active voice print already exists for the same speaker and resolved model, the service returns that existing voice print by default. Set forceRebuild=true to create a replacement.

Default Selection

If the first voice print for a speaker becomes READY, it is made the speaker default automatically. Later voice prints become default only when makeDefault=true is supplied or Set Default Voice Print is called.

SpeakerServiceVoicePrintResponse

Returns the existing active voice print or a newly created terminal voice print. New voice prints are returned as READY when the build succeeds or FAILED when post-creation build processing fails.

Status Description
200 OK Existing active voice print returned because forceRebuild=false.
201 Created Voice print created synchronously. Response includes Location.
400 Bad Request Invalid request body, model alias, or enrollment selection.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope or not authorized.
404 Not Found Speaker or selected enrollment not found.
409 Conflict Speaker is deleted, archived, disabled, model is not available for voice-print creation, or the speaker does not have the minimum usable READY enrollments.
422 Unprocessable Entity Required retained enrollment artifacts are unavailable or unusable.
429 Too Many Requests Voice-print creation rate limit exceeded.

Get Voice Print

GET /api/v1/speaker-services/speaker-verification/voice-prints/{voicePrintId}

Requires Authentication - Scopes: speaker:voiceprints:read

Retrieve a single voice print.

Status Description
200 OK Voice print retrieved successfully.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope or not authorized.
404 Not Found Voice print not found.

Activate Voice Print

POST /api/v1/speaker-services/speaker-verification/voice-prints/{voicePrintId}/activate

Requires Authentication - Scopes: speaker:voiceprints:write

Make a READY voice print the active voice print for its speaker and resolved model. Activating one voice print deactivates any other active voice print for the same speaker and resolved model.

SpeakerServiceVoicePrintResponse
Status Description
200 OK Voice print activated.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope or not authorized.
404 Not Found Voice print not found.
409 Conflict Voice print is not READY, is deleted, or is purged.

Set Default Voice Print

POST /api/v1/speaker-services/speaker-verification/voice-prints/{voicePrintId}/set-default

Requires Authentication - Scopes: speaker:voiceprints:write

Make a READY active voice print the speaker default. Verification requests that omit model use this voice print.

SpeakerServiceVoicePrintResponse
Status Description
200 OK Default voice print updated.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope or not authorized.
404 Not Found Voice print not found.
409 Conflict Voice print is not READY, not active, deleted, or purged.

Delete Voice Print

DELETE /api/v1/speaker-services/speaker-verification/voice-prints/{voicePrintId}

Requires Authentication - Scopes: speaker:voiceprints:delete

Soft-delete a voice print. Deleted voice prints cannot be used for verification. The same speaker:voiceprints:delete scope is used whether or not purge=true is supplied.

Query Parameters
Parameter Type Required Default Description
purge boolean No false Immediately purge embedding vectors/object keys and sensitive debug artifacts after soft-delete.
Status Description
204 No Content Voice print deleted successfully.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope or not authorized.
404 Not Found Voice print not found.
409 Conflict Voice print is already deleted or purged.

Purge Voice Print

POST /api/v1/speaker-services/speaker-verification/voice-prints/{voicePrintId}/purge

Requires Authentication - Scopes: speaker:voiceprints:delete

Permanently purge a deleted voice print. Purge removes embedding vectors, vector/object keys, model debug artifacts, and sensitive processing errors while preserving minimal administrative metadata.

Status Description
204 No Content Voice print purged successfully.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope or not authorized.
404 Not Found Voice print not found.
409 Conflict Voice print is not deleted or is already purged.

Data Types

SpeakerServiceVoicePrintResponse

Field Type Nullable Description
id string (UUID) No Unique voice print identifier.
speakerId string (UUID) No Speaker that owns the voice print.
status string No Voice print lifecycle status. See SpeakerVoicePrintStatus.
modelAlias string Yes Requested model alias used when the voice print was created.
resolvedModel string No Concrete resolved model name as a string.
modelHash string Yes Model space hash identifying the embedding vector space.
quality SpeakerServiceVoicePrintQuality Yes Voice print quality score and level.
sourceEnrollments SpeakerServiceEnrollmentEmbeddingSource[] Yes Enrollment and embedding pairs used to build this voice print. Present for successfully built voice prints.
sourceEnrollmentCount integer No Number of source enrollments.
isActive boolean No Whether this is active for its resolved model.
isDefault boolean No Whether this is the speaker default voice print.
errorCode string Yes Top-level processing error when creation failed.
errors SpeakerServiceProcessingError[] Yes Processing errors for failed voice print creation.
isDeleted boolean No Whether the voice print has been soft-deleted.
isPurged boolean No Whether biometric artifacts have been permanently removed.
createdAt string (ISO 8601) No Timestamp when the voice print resource was created.
completedAt string (ISO 8601) Yes Timestamp when voice print creation reached a terminal state.
activatedAt string (ISO 8601) Yes Timestamp when the voice print became active.
defaultedAt string (ISO 8601) Yes Timestamp when the voice print became the speaker default.
deletedAt string (ISO 8601) Yes Timestamp when the voice print was deleted.
purgedAt string (ISO 8601) Yes Timestamp when biometric artifacts were purged.
purgeAt string (ISO 8601) Yes Scheduled purge timestamp based on retention policy.

SpeakerServiceVoicePrintPreviewResponse

Field Type Nullable Description
enrollmentCount integer No Number of source enrollments evaluated.
embeddingCount integer No Number of embedding vectors extracted from the enrollments.
qualityScore float No Aggregated quality score from 0.0 to 1.0.
qualityLevel string No Quality band derived from the score. Values: UNKNOWN, POOR, FAIR, GOOD, EXCELLENT.
minSimilarity float Yes Lowest pairwise similarity between enrollment embeddings.
maxSimilarity float Yes Highest pairwise similarity between enrollment embeddings.
outlierEnrollmentIds string[] (UUID) No Enrollment IDs identified as outliers in the centroid computation.
recommendation string No Actionable recommendation. Values: ADD_MORE_ENROLLMENTS, REMOVE_OUTLIERS, READY_TO_BUILD.
SpeakerServiceVoicePrintPreviewResponse (example)
{
  "enrollmentCount": 5,
  "embeddingCount": 12,
  "qualityScore": 0.82,
  "qualityLevel": "GOOD",
  "minSimilarity": 0.71,
  "maxSimilarity": 0.95,
  "outlierEnrollmentIds": [],
  "recommendation": "READY_TO_BUILD"
}

QualityRecommendation

Value Description
ADD_MORE_ENROLLMENTS The speaker does not have enough enrollments, or the quality score is too low. Add more enrollments and preview again.
REMOVE_OUTLIERS Too many enrollment embeddings are outliers. Remove the identified outlier enrollments and preview again.
READY_TO_BUILD Quality is sufficient - proceed to create a voice print.

SpeakerServiceVoicePrintSummary

Field Type Nullable Description
id string (UUID) No Voice print identifier.
modelAlias string Yes Alias requested when the voice print was created.
resolvedModel string No Concrete resolved model name.
quality SpeakerServiceVoicePrintQuality Yes Voice print quality summary.
createdAt string (ISO 8601) No Timestamp when the voice print was created.

SpeakerServiceEnrollmentEmbeddingSource

Field Type Nullable Description
enrollmentId string (UUID) No Source enrollment identifier.
embeddingId string (UUID) Yes Embedding record identifier extracted from this enrollment.

SpeakerServiceVoicePrintQuality

Field Type Nullable Description
score float Yes Aggregated quality score from 0.0 to 1.0.
level string No Quality band derived from the quality score. Values: UNKNOWN, POOR, FAIR, GOOD, EXCELLENT.

Enumerations

SpeakerVoicePrintStatus

Value Description
READY Voice print is available for activation and verification.
FAILED Voice print creation failed.

Deletion and Purge

Deletion and purge state are tracked via the isDeleted and isPurged boolean fields on the voice print response, not as status enum values. This is consistent with speakers and enrollments.