HTTP API

Server aktivieren#

1. Öffne Einstellungen > Erweitert > API-Server.
2. Schalte „HTTP-API aktivieren“ ein; der Server startet sofort. Für einen anderen Port als 8978 trägst du ihn ein und wählst „Anwenden“.
3. Prüfe den Status in PowerShell. Hast du einen anderen Port gewählt, setze ihn hier und in den folgenden Beispielen ein:

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

Discovery und Token#

Beim Start schreibt der Server zwei Discovery-Dateien in deinen Profilordner, bei der direkten Installation %LOCALAPPDATA%\TypeWhisper-WinUI: api-discovery.json mit Port, Token, Adresse, API-Version, Prozess-ID und der Angabe, ob ein Token verlangt wird, sowie die ältere Datei api-port. Wo die Microsoft-Store-Version ihr Profil ablegt, steht unter Datenablage und Deinstallation.

{
  "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-Authentifizierung ist optional: Schalte „API-Token verlangen“ ein und wähle „Anwenden“. /v1/status bleibt dann öffentlich. Sende das Token bei allen anderen API-Anfragen als Bearer-Token oder im Header X-TypeWhisper-API-Token.

$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"

Audio transkribieren#

Sende eine Datei als multipart/form-data. language und language_hint schließen sich gegenseitig aus; language_hint darf mehrfach und in Prioritätsreihenfolge vorkommen.

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"

Weitere Felder: task (transcribe oder translate), target_language, prompt, engine und model. Mit await_download=1 wartet die Anfrage bei unterstützten lokalen Engines auf Download oder Wiederherstellung des Modells.

Für bereits lokale Dateien akzeptiert /v1/transcribe/local-file einen Windows-Pfad als JSON. Dadurch muss eine große Datei nicht nochmals durch den API-Prozess hochgeladen werden.

Modelle laden, entladen und löschen#

Übergib die Werte engine und id aus GET /v1/models als engine und model. POST /v1/models/load lädt das Modell und wählt es für die Transkription aus. Heruntergeladen wird dabei nichts: Lade ein lokales Modell zuerst in TypeWhisper herunter oder lass es von einer Transkriptionsanfrage mit engine, model und await_download=1 herunterladen. Die Antwort kommt, sobald das Modell geladen ist oder das Laden fehlgeschlagen ist.

Parakeet meldet die Engine sherpa-onnx, whisper.cpp meldet whisper-cpp. Als engine nimmt die API auch die provider_id des Modells oder die Paket-ID des Plugins an, etwa com.typewhisper.sherpa-onnx.

Die Beispiele übergeben JSON-Bodys per Pipeline an curl.exe (--data-binary "@-"), weil Windows PowerShell 5.1 die Anführungszeichen aus JSON entfernt, das als Argument übergeben wird:

'{"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"
}

Jede Route liefert engine, model und status; status ist ready, unloaded oder deleted, und engine wiederholt den Wert aus der Anfrage. POST /v1/models/unload braucht nur engine und ignoriert model. Die Route entlädt das Modell der Engine und behält die heruntergeladenen Dateien. In der Antwort ist model das Modell, das geladen war (Parakeet), oder das ausgewählte Modell der Engine (andere Engines), und null, wenn es keins gibt. Nach dem Entladen von Parakeet hat TypeWhisper kein Modell bereit, bis du wieder eines lädst.

DELETE /v1/models erwartet engine und model als Query-Parameter und entfernt die heruntergeladenen Modelldateien. Das funktioniert bei lokalen Engines, deren Plugin Modelldateien entfernen kann, etwa Parakeet und whisper.cpp. Das Modell, das eine Engine ausgewählt hat oder noch geladen haben könnte, ist geschützt und ergibt 409: Lade zuerst ein anderes Modell dieser Engine und entlade bei anderen Engines als Parakeet zusätzlich die Engine.

Ungültiges JSON oder ein fehlendes engine ergibt 400, beim Laden und Löschen auch ein fehlendes model. Eine unbekannte Engine oder ein Modell, das die Engine nicht anbietet, ergibt 404, ebenso das Löschen eines Modells, das nicht heruntergeladen ist. Mit 409 antworten die Routen, wenn die Engine die Aktion nicht ausführen kann, wenn TypeWhisper gerade diktiert, aufnimmt, eine Datei transkribiert oder einen anderen Modellvorgang ausführt, und wenn das zu ladende Modell nicht heruntergeladen ist. Cloud-Engines haben zum Beispiel kein lokales Modell, das sich entladen oder löschen ließe. Eine Anfrage, die länger als fünf Minuten dauert, endet mit 408.

Ab TypeWhisper für Windows 1.2 können verwaltete Einstellungen diese Routen mit 403 ablehnen. Alle drei antworten mit 403 für eine Engine, die die Richtlinie nicht erlaubt, etwa eine Cloud-Engine bei ausgeschalteter Cloud-Transkription oder jede andere Engine als die erzwungene. Erzwingt die Richtlinie Engine und Modell, antwortet POST /v1/models/load auch für jedes andere Modell dieser Engine mit 403.

Stabile Endpunkte#

Workflow-Kompatibilitätsrouten#

/v1/rules und /v1/profiles sowie ihre PUT-Routen /toggle bleiben für bestehende Integrationen erhalten. Beide liefern die heutige Workflow-Konfiguration; für neue Oberflächen und Dokumentation heißt das Konzept Workflows.