API Reference

GET /health

Returns service metadata and the currently exposed public STT model alias.

Authentication:

• None

Response:

{
  "serviceId": "uuid",
  "version": "0.1.7",
  "publicModel": "vilab-local-stt"
}

publicModel always reflects the current STT routing result:

• In Local mode, it maps to the exposed alias for the active local speech model. The public alias remains vilab-local-stt even when the active built-in runtime is Whisper Base, Whisper Small, or SenseVoice
• In Cloud mode, it maps to the exposed alias for the selected cloud STT provider/model

GET /v1/models

Returns the public model list exposed by VILab.

Authentication:

• Authorization: Bearer <external_api_key>

Response:

{
  "object": "list",
  "data": [
    {
      "id": "vilab-local-stt",
      "object": "model",
      "created": 0,
      "owned_by": "vilab"
    }
  ]
}

If STT mode is Local and no local speech model is active yet, data is returned as an empty array.

POST /v1/audio/transcriptions

Accepts multipart form data and returns a transcription.

Authentication:

• Authorization: Bearer <external_api_key>

Form fields:

• file: required audio file. This phase accepts WAV input.
• model: optional, defaults to the current public STT alias returned by /health
• language: optional
• response_format: optional, json by default, text also supported

When STT mode is Local, the active local runtime behind this endpoint can be either Whisper or SenseVoice, depending on which local speech model is currently activated in Settings.

JSON response:

{
  "text": "transcribed content"
}

Plain text response:

• Set response_format=text
• Response content type becomes text/plain; charset=utf-8

Errors:

• 400: missing file or unsupported model
• 401: invalid or missing bearer token
• 502: the current STT runtime failed to transcribe the supplied audio

/admin/*

Admin endpoints are for host management only.

Examples:

• GET /admin/status
• GET /admin/providers
• PUT /admin/providers/{id}
• GET /admin/routing
• PUT /admin/routing
• GET /admin/api-keys
• POST /admin/api-keys
• POST /admin/api-keys/{id}/revoke

Authentication:

• Authorization: Bearer <adminKey>