Skip to content

Speaker Services - Speakers

Manage speaker identities, readiness, default voice-print quality, and speaker lifecycle. Embedding model aliases are documented in Embedding Models, voice-print endpoints are documented in Voice Prints, enrollment endpoints are documented in Enrollments, and verification endpoints are documented in Verifications.

Base path: /api/v1/speaker-services

Method Endpoint Description
GET /api/v1/speaker-services/speaker-verification/speakers List Speakers
POST /api/v1/speaker-services/speaker-verification/speakers Create Speaker
GET /api/v1/speaker-services/speaker-verification/speakers/{id} Get Speaker
PATCH /api/v1/speaker-services/speaker-verification/speakers/{id} Update Speaker
DELETE /api/v1/speaker-services/speaker-verification/speakers/{id} Delete Speaker
POST /api/v1/speaker-services/speaker-verification/speakers/{id}/purge Purge Speaker

Recommended Enrollment Strategy

Enroll each speaker with 3 to 5 clean samples from different sessions, each containing at least 10 to 20 seconds of dominant speech. Avoid overlapping speakers, clipping, aggressive compression, and heavy background noise.

List Speakers

GET /api/v1/speaker-services/speaker-verification/speakers

Requires Authentication - Scopes: speaker:speakers:read

Retrieve a paginated list of speaker identities owned by the authenticated caller.

Query Parameters
Parameter Type Required Default Description
page integer No 0 Page number (zero-based).
size integer No 20 Page size (max 100).
status string[] No - Filter by speaker status. Values: ACTIVE, DISABLED, ARCHIVED.
verificationStatus string[] No - Filter by readiness state. Values: NOT_READY, READY, DEGRADED.
name string No - Partial case-insensitive search on display name.
externalRef string No - Exact match on a client-defined external identifier.
tags string[] No - Filter by tags (comma-separated). A speaker matches when it has at least one supplied tag.
createdAfter string (ISO 8601) No - Return speakers created on or after this timestamp.
createdBefore string (ISO 8601) No - Return speakers created on or before this timestamp.
voicePrintModel string No - Filter speakers whose default voice print was produced by this concrete resolved model.
voicePrintModelAlias string No - Filter speakers whose default voice print was created with this model alias.
voicePrintModelStatus string No - Filter speakers whose default voice print's resolved model has this status. Values: AVAILABLE, DEPRECATED, MAINTENANCE, INACTIVE.
isDeleted boolean No false Filter by deleted state.
sort string No creationDate,desc Sort field and direction. Allowed fields: name, creationDate, lastVerificationAt, status, voicePrintQuality.score, voicePrintModel. 
curl -X GET "https://koldan.dixilang.com/api/v1/speaker-services/speaker-verification/speakers?page=0&size=20&verificationStatus=READY" \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

resp = requests.get(
    "https://koldan.dixilang.com/api/v1/speaker-services/speaker-verification/speakers",
    headers={"Authorization": f"Bearer {JWT}"},
    params={"page": 0, "size": 20, "verificationStatus": "READY"}
)
print(resp.json())
SpeakerServiceSpeakersListResponse
Field Type Nullable Description
speakers SpeakerServiceSpeakerResponse[] No Array of speaker identities.
size integer No Number of items returned in this page.
total long No Total number of matching items across all pages.
filters object No Echo of applied filters.
sort object No Applied sort order.
Status Description
200 OK Speakers retrieved successfully.
400 Bad Request Invalid sort field or query parameters.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope.

Create Speaker

POST /api/v1/speaker-services/speaker-verification/speakers

Requires Authentication - Scopes: speaker:speakers:write

Create a new speaker identity.

SpeakerServiceCreateSpeakerRequest
Field Type Required Description
name string Yes Human-readable display name.
externalRef string No Client-defined business identifier. Must be unique per owner.
description string No Optional note describing the speaker.
locale string No Preferred IETF BCP 47 locale.
tags string[] No Optional tags for search and organization.
metadata object No Additional key-value metadata.
SpeakerServiceCreateSpeakerRequest
{
  "name": "Dana Levi",
  "externalRef": "crm-contact-1842",
  "description": "Primary contact for retail onboarding",
  "locale": "he-IL",
  "tags": ["Retail", "VIP"],
  "metadata": {
    "department": "sales"
  }
}
SpeakerServiceSpeakerResponse

Returns the created speaker.

Status Description
201 Created Speaker created successfully.
400 Bad Request Invalid request body or duplicate externalRef.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope.

Get Speaker

GET /api/v1/speaker-services/speaker-verification/speakers/{id}

Requires Authentication - Scopes: speaker:speakers:read

Retrieve a single speaker identity including enrollment readiness and voice-print quality.

Path Parameters
Parameter Type Required Description
id string (UUID) Yes Unique identifier of the speaker.
SpeakerServiceSpeakerResponse
SpeakerServiceSpeakerResponse
{
  "id": "0d5b31f3-2d77-4b46-a7b0-0d22b9910d10",
  "name": "Dana Levi",
  "status": "READY",
  "verificationStatus": "READY",
  "enrollmentSummary": {
    "total": 5,
    "successful": 4,
    "rejected": 1,
    "failed": 0,
    "minimumRequired": 1,
    "recommendedTarget": 3
  },
  "voicePrintQuality": {
    "score": 0.87,
    "level": "GOOD"
  },
  "defaultVoicePrint": {
    "id": "ddf851d2-2dcc-410e-8685-86f7a826d45e",
    "modelAlias": "speaker-default",
    "resolvedModel": "spk-embed-he-v3",
    "quality": {
      "score": 0.87,
      "level": "GOOD"
    },
    "createdAt": "2026-04-22T10:31:43Z"
  }
}
Status Description
200 OK Speaker retrieved successfully.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope or not authorized.
404 Not Found Speaker not found.

Update Speaker

PATCH /api/v1/speaker-services/speaker-verification/speakers/{id}

Requires Authentication - Scopes: speaker:speakers:write

Update mutable speaker metadata and administrative state.

Path Parameters
Parameter Type Required Description
id string (UUID) Yes Unique identifier of the speaker.
SpeakerServiceUpdateSpeakerRequest
Field Type Required Description
name string No Updated display name.
externalRef string No Updated external business identifier.
description string No Updated description.
locale string No Updated preferred locale.
status string No Administrative state: ACTIVE, DISABLED, ARCHIVED.
tags string[] No Replace all tags with a new array.
metadata object No Replace metadata object.

Archived Speakers

When a speaker is changed to ARCHIVED, new enrollments and verifications are rejected. Existing data is subject to retention policy.

SpeakerServiceSpeakerResponse
Status Description
200 OK Speaker updated successfully.
400 Bad Request Invalid patch payload or duplicate externalRef.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope or not authorized.
404 Not Found Speaker not found.

Delete Speaker

DELETE /api/v1/speaker-services/speaker-verification/speakers/{id}

Requires Authentication - Scopes: speaker:speakers:delete

Soft-delete a speaker identity. Deleted speakers cannot receive new enrollments or be verified.

Path Parameters
Parameter Type Required Description
id string (UUID) Yes Unique identifier of the speaker.
Query Parameters
Parameter Type Required Default Description
purge boolean No false Immediately purge biometric artifacts and enrollment media.
Status Description
204 No Content Speaker deleted successfully.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope or not authorized.
404 Not Found Speaker not found.
409 Conflict Speaker already deleted or has active enrollment processing.

Purge Speaker

POST /api/v1/speaker-services/speaker-verification/speakers/{id}/purge

Requires Authentication - Scopes: speaker:speakers:delete

Permanently purge a deleted speaker and all remaining biometric artifacts.

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

Data Types

SpeakerServiceSpeakerResponse

Field Type Nullable Description
id string (UUID) No Unique identifier of the speaker.
name string No Display name.
externalRef string Yes Client-defined external identifier.
description string Yes Optional description.
locale string Yes Preferred IETF BCP 47 locale.
status string No Administrative state. See SpeakerStatus.
verificationStatus string No Verification readiness state. See SpeakerVerificationStatus.
enrollmentSummary SpeakerServiceEnrollmentSummary No Enrollment readiness summary.
voicePrintQuality SpeakerServiceVoicePrintQuality No Current quality estimate for the speaker default voice print.
defaultVoicePrint SpeakerServiceVoicePrintSummary Yes Speaker default voice print used when verification omits model.
lastEnrollmentAt string (ISO 8601) Yes Timestamp of the most recent successful enrollment.
lastVerificationAt string (ISO 8601) Yes Timestamp of the most recent verification.
tags string[] Yes Tags assigned to the speaker.
metadata object Yes Additional key-value metadata.
isDeleted boolean No Whether the speaker has been deleted.
isPurged boolean No Whether biometric artifacts have been permanently removed.
creationDate string (ISO 8601) No Timestamp when the speaker was created.
deletedAt string (ISO 8601) Yes Timestamp when the speaker was deleted.
purgedAt string (ISO 8601) Yes Timestamp when the speaker was purged.

SpeakerServiceEnrollmentSummary

Field Type Nullable Description
total integer No Total number of non-deleted enrollments.
successful integer No Number of READY enrollments.
rejected integer No Number of REJECTED enrollments (policy gate rejections, e.g. sentence verification).
failed integer No Number of FAILED enrollments (unexpected system errors).
minimumRequired integer No Minimum successful (READY) enrollments required for voice-print creation. Configured server-side.
recommendedTarget integer No Recommended successful enrollment count for stronger matching. Configured server-side.

SpeakerServiceVoicePrintQuality

Field Type Nullable Description
score float Yes Aggregated voice-print quality score from 0.0 to 1.0. null when no quality score can be calculated.
level string No Quality band derived from the quality score. See SpeakerVoicePrintQualityLevel.

SpeakerServiceVoicePrintSummary

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

Enumerations

SpeakerStatus

Value Description
ACTIVE Speaker is active and may receive enrollments and verifications.
DISABLED Speaker is temporarily blocked from enrollment and verification.
ARCHIVED Speaker is retained for history but should not receive new activity.

SpeakerVerificationStatus

Value Description
NOT_READY Not enough successful enrollments for verification.
READY Speaker has enough successful enrollments and a default voice print for verification.
DEGRADED Speaker remains usable, but enrollment count or quality fell below the recommended target.

SpeakerVoicePrintQualityLevel

Value Description
UNKNOWN Quality cannot be calculated, usually because no successful enrollments exist.
POOR Voice print is not recommended for verification.
FAIR Voice print is usable but should be improved.
GOOD Voice print is suitable for normal verification.
EXCELLENT Voice print is strong and well represented.

Speaker Lifecycle

Speaker identities follow a lifecycle: active/disabled/archived → deleted → purged.