Skip to content

Administration - Models & Aliases

Manage speech models and model aliases. Speech models represent the underlying transcription engines, while aliases provide stable, user-facing identifiers that resolve to specific model versions.

Base path: /api/v1/speech-services/admin/models

Speech Model Management

Method Endpoint Description
GET /api/v1/speech-services/admin/models List All Models
POST /api/v1/speech-services/admin/models Register Model
POST /api/v1/speech-services/admin/models/{name}/upload Upload Model Binary
POST /api/v1/speech-services/admin/models/{name}/verify Verify Model Backend
PUT /api/v1/speech-services/admin/models/{name}/status Update Model Status
DELETE /api/v1/speech-services/admin/models/{name} Delete Model

Model Alias Management

Method Endpoint Description
GET /api/v1/speech-services/admin/aliases List All Aliases
PUT /api/v1/speech-services/admin/aliases/{alias} Create or Update Alias
PUT /api/v1/speech-services/admin/aliases/{alias}/resolve Update Alias Resolution
PUT /api/v1/speech-services/admin/aliases/{alias}/deprecate Deprecate Alias
DELETE /api/v1/speech-services/admin/aliases/{alias} Delete Alias

List All Models

GET /api/v1/speech-services/admin/models

Requires Authentication - Scopes: admin:models:write

Returns all registered speech models for the current tenant, including full backend configuration details.

curl -X GET https://koldan.dixilang.com/api/v1/speech-services/admin/models \
  -H "X-API-Key: $KOLDAN_API_KEY"
import requests

resp = requests.get(
    "https://koldan.dixilang.com/api/v1/speech-services/admin/models",
    headers={"Authorization": f"Bearer {JWT}"}
)
print(resp.json())
AdminModelResponse[]
Status Description
200 OK List of speech models returned.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope.

Register Model

POST /api/v1/speech-services/admin/models

Requires Authentication - Scopes: admin:models:write

Registers a new speech model with the specified backend type and configuration.

RegisterModelRequest
Field Type Required Description
name string Yes Unique model name (e.g. koldan-he-medical-v2.1).
displayName string Yes Human-readable display name.
description string No Model description.
backendType string Yes Backend type: INTERNAL, WERNICKE
backendId string Yes Backend configuration key from application config.
backendModelId string No Model ID within the backend (required for WERNICKE).
engineType string No Engine type: K2 or SLIBE (INTERNAL only).
modelArch string No Model architecture: ZIPFORMER, ZIPFORMER2, etc. (INTERNAL only).
engineConfig object No Engine-specific configuration map (INTERNAL only).
sampleRate integer No Sample rate in Hz (INTERNAL only).
supportedLanguages string[] Yes Supported BCP-47 language codes.
supportsLangAutodetect boolean No Whether the model supports automatic language detection. Default: false.
supportsStreaming boolean No Whether the model supports streaming transcription. Default: false.
curl -X POST https://koldan.dixilang.com/api/v1/speech-services/admin/models \
  -H "X-API-Key: $KOLDAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "koldan-he-medical-v2.1",
    "displayName": "Koldan Hebrew Medical v2.1",
    "description": "Hebrew medical transcription model",
    "backendType": "INTERNAL",
    "backendId": "default-k2",
    "engineType": "K2",
    "modelArch": "ZIPFORMER2",
    "sampleRate": 16000,
    "supportedLanguages": ["he"],
    "supportsStreaming": true
  }'
import requests

resp = requests.post(
    "https://koldan.dixilang.com/api/v1/speech-services/admin/models",
    headers={"Authorization": f"Bearer {JWT}"},
    json={
        "name": "koldan-he-medical-v2.1",
        "displayName": "Koldan Hebrew Medical v2.1",
        "backendType": "INTERNAL",
        "backendId": "default-k2",
        "engineType": "K2",
        "supportedLanguages": ["he"],
        "supportsStreaming": True
    }
)
print(resp.json())
AdminModelResponse
Status Description
200 OK Model registered successfully.
400 Bad Request Validation error (missing required fields, invalid backend type).
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope.
409 Conflict A model with the given name already exists.

Upload Model Binary

POST /api/v1/speech-services/admin/models/{name}/upload

Requires Authentication - Scopes: admin:models:write

Uploads a model binary file for an INTERNAL backend model. The file is stored in S3 and a SHA-256 hash is computed and stored.

Path Parameters
Parameter Type Required Description
name string Yes Name of the registered model.
Request Body (multipart/form-data)
Field Type Required Description
file binary Yes Model binary file (e.g. .tar archive).
curl -X POST https://koldan.dixilang.com/api/v1/speech-services/admin/models/koldan-he-medical-v2.1/upload \
  -H "X-API-Key: $KOLDAN_API_KEY" \
  -F "file=@model.tar"
import requests

with open("model.tar", "rb") as f:
    resp = requests.post(
        "https://koldan.dixilang.com/api/v1/speech-services/admin/models/koldan-he-medical-v2.1/upload",
        headers={"Authorization": f"Bearer {JWT}"},
        files={"file": ("model.tar", f, "application/x-tar")}
    )
print(resp.json())
ModelUploadResponse
Status Description
200 OK File uploaded successfully.
400 Bad Request Model is not an INTERNAL backend type.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope.
404 Not Found Model not found.

Verify Model Backend

POST /api/v1/speech-services/admin/models/{name}/verify

Requires Authentication - Scopes: admin:models:write

Performs backend connectivity and readiness checks for the specified model. The checks vary by backend type:

  • INTERNAL: Validates engine type configuration, backend configuration presence, discovery service name, and engine instance registration.
  • WERNICKE: Validates backend configuration presence, performs a health check, and confirms backend model ID is set.
Path Parameters
Parameter Type Required Description
name string Yes Name of the registered model.
curl -X POST https://koldan.dixilang.com/api/v1/speech-services/admin/models/koldan-he-medical-v2.1/verify \
  -H "X-API-Key: $KOLDAN_API_KEY"
import requests

resp = requests.post(
    "https://koldan.dixilang.com/api/v1/speech-services/admin/models/koldan-he-medical-v2.1/verify",
    headers={"Authorization": f"Bearer {JWT}"}
)
print(resp.json())
VerifyModelResponse
Example Response
{
  "model": "koldan-he-medical-v2.1",
  "backendType": "INTERNAL",
  "status": "AVAILABLE",
  "checks": [
    {
      "name": "engine_type_configured",
      "passed": true,
      "detail": "Engine type: K2"
    },
    {
      "name": "backend_configured",
      "passed": true,
      "detail": "Backend 'default-k2' found in configuration"
    },
    {
      "name": "discovery_service_name",
      "passed": true,
      "detail": "Discovery service name: koldan-engine-k2"
    },
    {
      "name": "engine_discovery",
      "passed": true,
      "detail": "Engine instance found at 10.0.1.5:50051"
    }
  ]
}
Status Description
200 OK Verification results returned.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope.
404 Not Found Model not found.

Update Model Status

PUT /api/v1/speech-services/admin/models/{name}/status

Requires Authentication - Scopes: admin:models:write

Updates the availability status of a speech model.

Path Parameters
Parameter Type Required Description
name string Yes Name of the registered model.
UpdateModelStatusRequest
Field Type Required Description
status string Yes New status: AVAILABLE, UNAVAILABLE, MAINTENANCE, or DEPRECATED.
statusMessage string No Optional status message (e.g. reason for maintenance).
curl -X PUT https://koldan.dixilang.com/api/v1/speech-services/admin/models/koldan-he-medical-v2.1/status \
  -H "X-API-Key: $KOLDAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "MAINTENANCE",
    "statusMessage": "Scheduled maintenance window"
  }'
import requests

resp = requests.put(
    "https://koldan.dixilang.com/api/v1/speech-services/admin/models/koldan-he-medical-v2.1/status",
    headers={"Authorization": f"Bearer {JWT}"},
    json={
        "status": "MAINTENANCE",
        "statusMessage": "Scheduled maintenance window"
    }
)
print(resp.json())
AdminModelResponse
Status Description
200 OK Status updated successfully.
400 Bad Request Invalid status value.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope.
404 Not Found Model not found.

Delete Model

DELETE /api/v1/speech-services/admin/models/{name}

Requires Authentication - Scopes: admin:models:delete

Deletes a registered speech model. Aliases referencing this model must be removed first.

Path Parameters
Parameter Type Required Description
name string Yes Name of the model to delete.
curl -X DELETE https://koldan.dixilang.com/api/v1/speech-services/admin/models/koldan-he-medical-v2.1 \
  -H "X-API-Key: $KOLDAN_API_KEY"
import requests

resp = requests.delete(
    "https://koldan.dixilang.com/api/v1/speech-services/admin/models/koldan-he-medical-v2.1",
    headers={"Authorization": f"Bearer {JWT}"}
)
print(resp.status_code)  # 204
Status Description
204 No Content Model deleted successfully.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope.
404 Not Found Model not found.
409 Conflict Model is still referenced by one or more aliases.

List All Aliases

GET /api/v1/speech-services/admin/aliases

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

Returns all model aliases for the current tenant, including deprecated aliases.

curl -X GET https://koldan.dixilang.com/api/v1/speech-services/admin/aliases \
  -H "X-API-Key: $KOLDAN_API_KEY"
import requests

resp = requests.get(
    "https://koldan.dixilang.com/api/v1/speech-services/admin/aliases",
    headers={"Authorization": f"Bearer {JWT}"}
)
print(resp.json())
ModelAliasResponse[]
Status Description
200 OK List of model aliases returned.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope.

Create or Update Alias

PUT /api/v1/speech-services/admin/aliases/{alias}

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

Creates a new model alias or updates an existing one. The alias maps a stable user-facing identifier to a specific speech model version.

Path Parameters
Parameter Type Required Description
alias string Yes Alias identifier (e.g. hebrew-general).
CreateUpdateAliasRequest
Field Type Required Description
resolvedModel string Yes Name of the speech model this alias resolves to.
fallbackModel string No Name of a fallback speech model (used when primary is unavailable).
type string Yes Alias type: FAMILY, PINNED, or CONCRETE.
displayName string Yes Human-readable display name.
description string No Alias description.
isDefault boolean No Whether this alias is the default for the tenant. Default: false.
roles string[] No Role slugs (e.g. admin, manager, user, viewer) allowed to use this alias. Empty list means accessible to all roles.
curl -X PUT https://koldan.dixilang.com/api/v1/speech-services/admin/aliases/hebrew-general \
  -H "X-API-Key: $KOLDAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resolvedModel": "koldan-he-medical-v2.1",
    "type": "FAMILY",
    "displayName": "Hebrew General",
    "description": "General-purpose Hebrew transcription",
    "roles": ["admin", "user"]
  }'
import requests

resp = requests.put(
    "https://koldan.dixilang.com/api/v1/speech-services/admin/aliases/hebrew-general",
    headers={"Authorization": f"Bearer {JWT}"},
    json={
        "resolvedModel": "koldan-he-medical-v2.1",
        "type": "FAMILY",
        "displayName": "Hebrew General",
        "description": "General-purpose Hebrew transcription",
        "roles": ["admin", "user"]
    }
)
print(resp.json())
ModelAliasResponse
Status Description
200 OK Alias created or updated successfully.
400 Bad Request Validation error (missing required fields, invalid type).
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope.

Update Alias Resolution

PUT /api/v1/speech-services/admin/aliases/{alias}/resolve

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

Updates which speech model an alias resolves to, without changing other alias properties.

Path Parameters
Parameter Type Required Description
alias string Yes Alias identifier.
UpdateAliasResolutionRequest
Field Type Required Description
resolvedModel string Yes Name of the new resolved speech model.
fallbackModel string No Name of the new fallback model (null to remove).
curl -X PUT https://koldan.dixilang.com/api/v1/speech-services/admin/aliases/hebrew-general/resolve \
  -H "X-API-Key: $KOLDAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resolvedModel": "koldan-he-general-v3.0",
    "fallbackModel": "koldan-he-medical-v2.1"
  }'
import requests

resp = requests.put(
    "https://koldan.dixilang.com/api/v1/speech-services/admin/aliases/hebrew-general/resolve",
    headers={"Authorization": f"Bearer {JWT}"},
    json={
        "resolvedModel": "koldan-he-general-v3.0",
        "fallbackModel": "koldan-he-medical-v2.1"
    }
)
print(resp.json())
ModelAliasResponse
Status Description
200 OK Alias resolution updated successfully.
400 Bad Request Validation error.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope.
404 Not Found Alias or target model not found.

Deprecate Alias

PUT /api/v1/speech-services/admin/aliases/{alias}/deprecate

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

Marks a model alias as deprecated with an optional sunset date. Deprecated aliases continue to function but clients receive deprecation warnings.

Path Parameters
Parameter Type Required Description
alias string Yes Alias identifier.
DeprecateAliasRequest
Field Type Required Description
deprecationDate string (date) No Date when the alias becomes deprecated (ISO 8601, e.g. 2026-06-01).
sunsetDate string (date) No Date when the alias will be removed.
message string No Deprecation message for users.
curl -X PUT https://koldan.dixilang.com/api/v1/speech-services/admin/aliases/hebrew-general/deprecate \
  -H "X-API-Key: $KOLDAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deprecationDate": "2026-06-01",
    "sunsetDate": "2026-12-01",
    "message": "Use hebrew-general-v2 instead"
  }'
import requests

resp = requests.put(
    "https://koldan.dixilang.com/api/v1/speech-services/admin/aliases/hebrew-general/deprecate",
    headers={"Authorization": f"Bearer {JWT}"},
    json={
        "deprecationDate": "2026-06-01",
        "sunsetDate": "2026-12-01",
        "message": "Use hebrew-general-v2 instead"
    }
)
print(resp.json())
ModelAliasResponse
Status Description
200 OK Alias deprecated successfully.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope.
404 Not Found Alias not found.

Delete Alias

DELETE /api/v1/speech-services/admin/aliases/{alias}

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

Deletes a model alias. Users referencing this alias will no longer be able to resolve it.

Path Parameters
Parameter Type Required Description
alias string Yes Alias identifier.
curl -X DELETE https://koldan.dixilang.com/api/v1/speech-services/admin/aliases/hebrew-general \
  -H "X-API-Key: $KOLDAN_API_KEY"
import requests

resp = requests.delete(
    "https://koldan.dixilang.com/api/v1/speech-services/admin/aliases/hebrew-general",
    headers={"Authorization": f"Bearer {JWT}"}
)
print(resp.status_code)  # 204
Status Description
204 No Content Alias deleted successfully.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope.
404 Not Found Alias not found.

Data Models

AdminModelResponse

Full speech model details returned by admin model endpoints.

Field Type Description
name string Model name (unique identifier).
displayName string Human-readable display name.
description string Model description.
backendType string Backend type: INTERNAL, WERNICKE.
backendId string Backend configuration key.
backendModelId string Model ID within the backend.
engineType string Engine type: K2 or SLIBE.
modelArch string Model architecture.
engineConfig object Engine-specific configuration map.
sampleRate integer Sample rate in Hz.
supportedLanguages string[] Supported BCP-47 language codes.
supportsLangAutodetect boolean Whether the model supports automatic language detection.
supportsStreaming boolean Whether the model supports streaming transcription.
status string Current status: AVAILABLE, UNAVAILABLE, MAINTENANCE, or DEPRECATED.
statusMessage string Status message.
fileHash string SHA-256 hash of the uploaded model file.
createdAt string (ISO 8601) Creation timestamp.
updatedAt string (ISO 8601) Last update timestamp.

RegisterModelRequest

Field Type Required Description
name string Yes Unique model name.
displayName string Yes Human-readable display name.
description string No Model description.
backendType string Yes Backend type: INTERNAL, WERNICKE.
backendId string Yes Backend configuration key.
backendModelId string No Model ID within the backend (required for WERNICKE).
engineType string No Engine type: K2 or SLIBE (INTERNAL only).
modelArch string No Model architecture (INTERNAL only).
engineConfig object No Engine-specific configuration (INTERNAL only).
sampleRate integer No Sample rate in Hz (INTERNAL only).
supportedLanguages string[] Yes Supported BCP-47 language codes.
supportsLangAutodetect boolean No Supports automatic language detection. Default: false.
supportsStreaming boolean No Supports streaming transcription. Default: false.

UpdateModelStatusRequest

Field Type Required Description
status string Yes New status: AVAILABLE, UNAVAILABLE, MAINTENANCE, or DEPRECATED.
statusMessage string No Optional status message.

ModelUploadResponse

Field Type Description
model string Model name.
fileHash string SHA-256 hash of the uploaded file.
message string Upload result message.

VerifyModelResponse

Field Type Description
model string Model name.
backendType string Backend type.
status string Current model status.
checks VerifyCheck[] Verification checks performed.

VerifyCheck

Field Type Description
name string Check name (e.g. engine_type_configured, backend_configured, backend_health).
passed boolean Whether the check passed.
detail string Check detail or error message.

ModelAliasResponse

Field Type Description
id string Model alias identifier.
type string Alias type: FAMILY, PINNED, or CONCRETE.
displayName string Human-readable display name.
description string Model description.
status string Model availability status.
currentVersion string Current resolved model version name.
capabilities ModelCapabilitiesResponse Model capabilities.
deprecated boolean Whether the model alias is deprecated.
deprecationDate string (date) Date when the alias was deprecated.
deprecationMessage string Deprecation message.

ModelCapabilitiesResponse

Field Type Description
languages string[] Supported BCP-47 language codes.
supportsLangAutodetect boolean Whether the model supports automatic language detection.
supportsStreaming boolean Whether the model supports streaming transcription.

CreateUpdateAliasRequest

Field Type Required Description
resolvedModel string Yes Name of the speech model this alias resolves to.
fallbackModel string No Name of the fallback speech model.
type string Yes Alias type: FAMILY, PINNED, or CONCRETE.
displayName string Yes Human-readable display name.
description string No Alias description.
isDefault boolean No Whether this alias is the default for the tenant. Default: false.
roles string[] No Role slugs allowed to use this alias. Empty list means accessible to all roles.

UpdateAliasResolutionRequest

Field Type Required Description
resolvedModel string Yes Name of the new resolved speech model.
fallbackModel string No Name of the new fallback model (null to remove).

DeprecateAliasRequest

Field Type Required Description
deprecationDate string (date) No Date when the alias becomes deprecated (ISO 8601).
sunsetDate string (date) No Date when the alias will be removed.
message string No Deprecation message for users.

Enumerations

BackendType

Value Description
INTERNAL Self-hosted speech engine (K2 or SLIBE). Supports model file upload.
WERNICKE External Wernicke speech service backend.

ModelStatus

Value Description
AVAILABLE Model is active and ready for transcription.
UNAVAILABLE Model is temporarily unavailable.
MAINTENANCE Model is under maintenance.
DEPRECATED Model is deprecated and scheduled for removal.

AliasType

Value Description
FAMILY A model family alias that can be updated to point to newer versions.
PINNED An alias pinned to a specific model version.
CONCRETE A direct alias to a concrete model.