HTTP API

Enable the server#

1. Open Settings > Advanced > API server.
2. Turn on Enable HTTP API; the server starts right away. To use a port other than 8978, enter it and select Apply.
3. Check the status from PowerShell. If you chose another port, use it here and in the examples below:

curl.exe http://localhost:8978/v1/status

Discovery and token#

When it starts, the server writes two discovery files to your profile folder, which is %LOCALAPPDATA%\TypeWhisper-WinUI for the direct download: api-discovery.json with port, token, address, API version, process ID, and whether a token is required, plus the legacy api-port file. For where the Microsoft Store edition keeps its profile, see Data location and uninstall.

{
  "version": 1,
  "token": "...",
  "host": "127.0.0.1",
  "port": 8978,
  "base_url": "http://127.0.0.1:8978",
  "api_version": "1.2",
  "pid": 12345,
  "requires_authentication": false
}

Token authentication is optional: turn on Require API token and select Apply. /v1/status then stays public. Send the token with every other API request as a bearer token or the X-TypeWhisper-API-Token header.

$discovery = Get-Content "$env:LOCALAPPDATA\TypeWhisper-WinUI\api-discovery.json" | ConvertFrom-Json
curl.exe -H "Authorization: Bearer $($discovery.token)" "http://localhost:$($discovery.port)/v1/models"

Transcribe audio#

Send a file as multipart/form-data. language and language_hint are mutually exclusive; language_hint may be repeated in priority order.

curl.exe -X POST http://localhost:8978/v1/transcribe `
  -F "file=@recording.wav" `
  -F "language_hint=de" `
  -F "language_hint=en" `
  -F "response_format=verbose_json"

Additional fields: task (transcribe or translate), target_language, prompt, engine, and model. Add await_download=1 to wait for a supported local engine to download or restore the model.

For files already on this machine, /v1/transcribe/local-file accepts a Windows path as JSON. This avoids uploading a large local file through the API process.

Load, unload, and delete models#

Pass the engine and id values from GET /v1/models as engine and model. POST /v1/models/load loads the model and selects it for transcription. It does not download anything: download a local model in TypeWhisper first, or let a transcription request with engine, model, and await_download=1 download it. The request returns once the model is loaded or loading has failed.

Parakeet reports the engine sherpa-onnx, and whisper.cpp reports whisper-cpp. As engine, the API also accepts the model's provider_id or the plugin's package ID, such as com.typewhisper.sherpa-onnx.

The examples pipe JSON bodies to curl.exe (--data-binary "@-"), because Windows PowerShell 5.1 strips the double quotes from JSON passed as an argument:

'{"engine":"sherpa-onnx","model":"parakeet-tdt-0.6b"}' |
  curl.exe -X POST http://localhost:8978/v1/models/load `
    -H "Content-Type: application/json" --data-binary "@-"

'{"engine":"sherpa-onnx"}' |
  curl.exe -X POST http://localhost:8978/v1/models/unload `
    -H "Content-Type: application/json" --data-binary "@-"

curl.exe -X DELETE `
  "http://localhost:8978/v1/models?engine=sherpa-onnx&model=canary-180m-flash"

{
  "engine": "sherpa-onnx",
  "model": "parakeet-tdt-0.6b",
  "status": "ready"
}

Each route returns engine, model, and status, which is ready, unloaded, or deleted; engine repeats the value from the request. POST /v1/models/unload needs only engine and ignores model. It unloads the engine's model and keeps the downloaded files. In its response, model is the model that was loaded (Parakeet) or the engine's selected model (other engines), and null if there is none. After you unload Parakeet, TypeWhisper has no model ready until you load one again.

DELETE /v1/models takes engine and model as query parameters and removes the downloaded model files. This works for local engines whose plugin can remove model files, such as Parakeet and whisper.cpp. The model an engine has selected or may still have loaded is protected and returns 409: load another model of that engine first and, for engines other than Parakeet, unload the engine as well.

Invalid JSON or a missing engine returns 400, and so does a missing model for load and delete. An unknown engine or a model the engine does not offer returns 404, and so does deleting a model that is not downloaded. The routes return 409 when the engine cannot perform the action, when TypeWhisper is dictating, recording, transcribing a file, or running another model operation, and when the model to load is not downloaded. Cloud engines, for example, have no local model to unload or delete. A request that runs longer than five minutes ends with 408.

From TypeWhisper for Windows 1.2, managed settings can refuse these routes with 403. All three answer 403 for an engine the policy does not allow, for example a cloud engine while cloud transcription is turned off, or any engine other than the enforced one. When the policy enforces an engine and model, POST /v1/models/load also answers 403 for any other model of that engine.

Stable endpoints#

Workflow compatibility routes#

/v1/rules and /v1/profiles and their PUT /toggle routes remain available for existing integrations. Both expose the current workflow configuration; new interfaces and documentation call the concept Workflows.