Skip to content

Speaker Services - Overview

Speaker Services provide speaker identity, enrollment, voice-print, embedding-model discovery, and verification APIs. Speaker verification resources are grouped under /api/v1/speaker-services/speaker-verification, while embedding model APIs remain under /api/v1/speaker-services/speaker-embeddings.

Services

Service Purpose Main docs
Speakers Manage speaker identities, lifecycle state, readiness, and the speaker default voice print summary. Speakers
Enrollments Upload source recordings and reset a speaker's enrollment process. Enrollments are model-agnostic audio samples. Enrollments
Voice Prints Build, activate, default, delete, and purge voice prints from usable enrollments for a selected embedding model alias. Voice Prints
Verifications Run speaker verification and optionally retain probe recordings. Verifications
Embedding Models Discover embedding model aliases used by voice-print and verification requests. Embedding Models
Sentence Verification Models Discover sentver aliases that can be selected by enrollment and verification requests. Sentence Verification Models
Analytics Pre-aggregated verification statistics (success/error rates, accept/review/reject rates) sliced by time period, speaker, model alias, resolved model, and voice print - with HTTP Cache-Control headers. Analytics

Core Concepts

  • Speakers are user-owned identities. A newly created speaker starts as ACTIVE. The separate verificationStatus field (NOT_READY, READY, DEGRADED) tracks whether a speaker has enough usable enrollments and a default voice print for verification.
  • Enrollments are speaker audio samples. Enrollment does not create a voice print automatically; it stores audio that can later be used to build voice prints for any embedding model.
  • Voice Prints are biometric resources built from enrollments for a specific embedding model alias. They include quality metrics and lifecycle flags (active/default).
  • Verifications run synchronously and return a decision with a score, thresholds, and the selected voice print.
  • Embedding model aliases are the model selection surface. Clients pass aliases only. Responses include resolvedModel so clients can see which concrete model handled a request.

Voice Print Selection

Verification always uses a ready, active voice print:

  • No model alias provided: the speaker's default voice print is used.
  • Model alias provided: the service resolves the alias and selects a matching active voice print.
  • If no suitable voice print exists and on-the-fly generation is enabled (default), the service builds one automatically if the speaker has enough enrollments.
  • If no voice print can be resolved, the API returns 409 VOICE_PRINT_NOT_READY_FOR_MODEL.

Data Retention

Recordings, biometric data, and verification records are subject to configurable retention policies. Contact your administrator for details on retention periods and data lifecycle.

Rate Limits and Quotas

Speaker Services enforce per-tenant rate limits and monthly quotas on enrollments, verifications, voice-print builds, and storage. When a limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header. Contact your administrator for details on your current limits.

Typical Integration Path

  1. Create a speaker with Speakers.
  2. Submit enough Enrollments. Enrollment creation is synchronous - the response contains the final status.
  3. (Optional) Preview voice print quality to check enrollment cohesion before building. Follow the recommendation (ADD_MORE_ENROLLMENTS, REMOVE_OUTLIERS, or READY_TO_BUILD).
  4. Create a Voice Print for the desired embedding model alias. Voice-print creation is synchronous and returns READY or FAILED. Alternatively, skip explicit voice print creation - verification can build voice prints on-the-fly when a speaker has enough enrollments.
  5. Run synchronous Verifications. Omit model to use the speaker default voice print, or provide an alias for a specific model. If no suitable voice print exists and on-the-fly generation is enabled (default), the service builds one automatically.
  6. Add sentenceVerification when the audio must contain a known sentence. Sentver models are discovered through Sentence Verification Models.
  7. Query Analytics to monitor success/error rates and accept/review/reject rates over time. Filter by speakerId, model, resolvedModel, or voicePrintId to drill into specific dimensions.