Admin - Speaker Embedding Models

Administer concrete embedding model configurations and manage embedding model aliases. User-facing alias discovery endpoints are documented in Embedding Models.

Admin base path: /api/v1/speaker-services/admin

Admin Model Management

Admin List Embedding Models

GET /api/v1/speaker-services/admin/speaker-embeddings/models

Requires Authentication - Scopes: admin:speaker-embedding-models:write

Returns concrete embedding model configurations for the tenant.

Response: AdminSpeakerEmbeddingModelResponse[]

Register Embedding Model

POST /api/v1/speaker-services/admin/speaker-embeddings/models

Requires Authentication - Scopes: admin:speaker-embedding-models:write

Registers a concrete embedding model configuration. The name is immutable after creation and remains the concrete model identifier used by aliases and retained voice prints.

SpeakerEmbeddingModelAdminRequest

{
  "name": "spk-embed-he-v3",
  "displayName": "Hebrew Speaker Embedding v3",
  "status": "AVAILABLE",
  "supportedLocales": ["he-IL", "en-US"],
  "grpc": {
    "target": "dns:///speaker-embedding-prod:443",
    "tlsMode": "SYSTEM_TRUST",
    "authority": "speaker-embedding-prod",
    "deadlineMs": 30000,
    "maxInboundMessageBytes": 4194304,
    "metadata": {
      "x-client": "speaker-services"
    }
  }
}

Response: AdminSpeakerEmbeddingModelResponse

Update Embedding Model

PUT /api/v1/speaker-services/admin/speaker-embeddings/models/{name}

Requires Authentication - Scopes: admin:speaker-embedding-models:write

Replaces editable configuration for an existing concrete embedding model. Required fields must be supplied. Nullable fields may be supplied, omitted, or set to null; omitted nullable fields are cleared.

This endpoint is for configuration updates such as display text, locale coverage, timeout values, and inference server connection settings. It does not change which concrete model an alias resolves to and does not rebuild existing voice prints.

name is immutable and is not accepted in the request body. status is updated only through PATCH /models/{name}/status.

Path Parameters

UpdateSpeakerEmbeddingModelRequest

{
  "displayName": "Hebrew Speaker Embedding v3.1",
  "description": "Production Hebrew speaker embedding model",
  "supportedLocales": ["he-IL"],
  "grpc": {
    "target": "dns:///speaker-embedding-prod-v3:443",
    "tlsMode": "SYSTEM_TRUST",
    "authority": "speaker-embedding-prod",
    "deadlineMs": 45000
  }
}

{
  "displayName": "Hebrew Speaker Embedding v3.1",
  "grpc": {
    "target": "dns:///speaker-embedding-prod-v3:443",
    "tlsMode": "SYSTEM_TRUST",
    "deadlineMs": 45000
  }
}

Update Embedding Model Status

PATCH /api/v1/speaker-services/admin/speaker-embeddings/models/{name}/status

Requires Authentication - Scopes: admin:speaker-embedding-models:write

Updates a concrete model status. DEPRECATED means the model is still usable for existing voice prints during migration. When a concrete model becomes INACTIVE, voice-print retention starts for voice prints produced by that resolved model.

Path Parameters

UpdateSpeakerEmbeddingModelStatusRequest

{
  "status": "MAINTENANCE",
  "statusMessage": "Inference server maintenance"
}

Delete Embedding Model

DELETE /api/v1/speaker-services/admin/speaker-embeddings/models/{name}

Requires Authentication - Scopes: admin:speaker-embedding-models:delete

Deletes a concrete model only when no aliases or retained voice prints reference it.

Admin Alias Management

Admin List Embedding Model Aliases

GET /api/v1/speaker-services/admin/speaker-embeddings/model-aliases

Requires Authentication - Scopes: admin:speaker-embedding-model-aliases:write

Returns all embedding model aliases for the tenant.

Create or Update Embedding Model Alias

PUT /api/v1/speaker-services/admin/speaker-embeddings/model-aliases/{alias}

Requires Authentication - Scopes: admin:speaker-embedding-model-aliases:write

Creates or updates an alias. Exactly one alias per tenant can be marked as default.

SpeakerEmbeddingModelAliasAdminRequest

Update Embedding Model Alias Resolution

PUT /api/v1/speaker-services/admin/speaker-embeddings/model-aliases/{alias}/resolve

Requires Authentication - Scopes: admin:speaker-embedding-model-aliases:write

Changes the concrete model an alias resolves to. Existing voice prints keep their previous resolved model metadata; clients create replacement voice prints through the user-facing voice-print creation endpoint.

Deprecate Embedding Model Alias

PUT /api/v1/speaker-services/admin/speaker-embeddings/model-aliases/{alias}/deprecate

Requires Authentication - Scopes: admin:speaker-embedding-model-aliases:write

Marks an alias as deprecated and optionally sets a sunset date.

Undeprecate Embedding Model Alias

PUT /api/v1/speaker-services/admin/speaker-embeddings/model-aliases/{alias}/undeprecate

Requires Authentication - Scopes: admin:speaker-embedding-model-aliases:write

Removes the deprecated status from an embedding model alias, clearing the deprecation date, sunset date, and deprecation message. The alias becomes fully active again.

Path Parameters

Delete Embedding Model Alias

DELETE /api/v1/speaker-services/admin/speaker-embeddings/model-aliases/{alias}

Requires Authentication - Scopes: admin:speaker-embedding-model-aliases:delete

Deletes an alias. Existing voice prints keep their requested alias and resolved model metadata.

Data Types

AdminSpeakerEmbeddingModelResponse

SpeakerEmbeddingGrpcClientConfig

Embedding inference calls use round-robin load balancing. Targets may be a single host:port, a DNS target such as dns:///embedding-headless:443, an unprefixed list such as server-a:2222,server-b:2222, or the preferred explicit form static:///server-a:2222,server-b:2222. Static lists have fixed membership; use DNS for dynamic membership. DNS targets are refreshed periodically even while another endpoint remains healthy. TLS endpoints must share a certificate identity or use the authority override.

UpdateSpeakerEmbeddingGrpcClientConfig

ModelThresholdDefaults

Per-mode threshold defaults for a concrete model. All fields are optional and nullable. A null field means "use the global service default" for that mode. Thresholds are floating-point values in the range [0.0, 1.0].

{
  "strictAcceptThreshold": 0.88,
  "strictReviewThreshold": 0.78,
  "balancedAcceptThreshold": 0.72,
  "balancedReviewThreshold": 0.58,
  "lenientAcceptThreshold": 0.58,
  "lenientReviewThreshold": 0.42
}

GrpcTlsMode

SpeakerEmbeddingModelStatus