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
Model Alias Management
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.
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.
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 Python
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 ())
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).
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.
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.
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).
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.
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.
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).
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 Python
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 ())
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.
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).
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.
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.
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.
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.