HTTP API und CLI-Automatisierung

Einrichtung und Authentifizierung

Aktiviere den API-Server unter Einstellungen > Erweitert. Der Standard-Port ist 8978. Solange der Server läuft, schreibt TypeWhisper den aktiven Port und ein generiertes Token nach ~/Library/Application Support/TypeWhisper/api-discovery.json.

API-Token erforderlich ist aus Kompatibilitätsgründen standardmäßig ausgeschaltet. Ist die Option aktiv, sende das Discovery-Token für jeden Endpunkt außer GET /v1/status als Bearer-Token.

DISCOVERY="$HOME/Library/Application Support/TypeWhisper/api-discovery.json"
export TYPEWHISPER_API_PORT="$(jq -r '.port' "$DISCOVERY")"
export TYPEWHISPER_API_TOKEN="$(jq -r '.token' "$DISCOVERY")"

curl "http://127.0.0.1:$TYPEWHISPER_API_PORT/v1/models" \
  -H "Authorization: Bearer $TYPEWHISPER_API_TOKEN"

GET /v1/status bleibt für Bereitschaftsprüfungen öffentlich. Clients können dasselbe Token alternativ im X-TypeWhisper-API-Token Header senden.

Die Discovery-Datei wird mit ausschließlich für den Besitzer gesetzten Rechten (0600) angelegt und beim Stoppen des Servers entfernt. Die TypeWhisper-CLI erkennt Port und Token automatisch. Mit --port, --api-token und TYPEWHISPER_API_TOKEN kannst du sie explizit überschreiben.

Endpunkt-Referenz

Die folgende Tabelle entspricht allen 26 Routen der aktuellen macOS-Implementierung, einschließlich der beiden Legacy-Aliase unter /v1/profiles und der Einstellungs-Backup-Routen.

Status prüfen

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

{
  "status": "ready",
  "engine": "whisper",
  "model": "openai_whisper-large-v3_turbo",
  "api_version": "1.1",
  "supports_workflow_dictation": true,
  "supports_streaming": true,
  "supports_translation": true
}

status ist ready, wenn das gewählte Modell transkribieren kann, andernfalls no_model. Die Funktionsfelder beschreiben die aktuell gewählte Engine. Ohne Auswahl entfallen die optionalen Felder engine und model.

Audio transkribieren

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

{
  "text": "Hello, world!",
  "language": "en",
  "duration": 2.5,
  "processing_time": 0.8,
  "engine": "whisper",
  "model": "openai_whisper-large-v3_turbo",
  "segments": [
    { "start": 0, "end": 2.5, "text": "Hello, world!" }
  ]
}

Bei Raw-Body-Uploads leitet TypeWhisper das Audioformat aus Content-Type ab. Optionen werden über die entsprechenden Header X-Language, X-Language-Hints, X-Task, X-Target-Language, X-Response-Format, X-Prompt, X-Engine, X-Model, X-Normalize-Numbers und X-Apply-Corrections übergeben.

POST /v1/transcribe/local-file akzeptiert einen JSON-Body mit einem absoluten Pfad und denselben Optionen in snake_case. Die Route ist nur für Dateien sinnvoll, die der lokale TypeWhisper-Prozess lesen kann, und ist keine Remote-Datei-API.

Modelle auflisten

curl http://localhost:8978/v1/models

{
  "models": [
    {
      "id": "openai_whisper-large-v3_turbo",
      "engine": "whisper",
      "name": "Large v3 Turbo",
      "size_description": "~800 MB",
      "language_count": 99,
      "status": "ready",
      "selected": true,
      "downloaded": true,
      "loaded": true
    }
  ]
}

status ist ready oder not_configured. selected kennzeichnet die aktuelle Auswahl in der Oberfläche. downloaded und loaded werden ausgegeben, wenn die Engine diese Zustände melden kann.

Verlauf

curl "http://localhost:8978/v1/history?q=meeting&limit=10&offset=0"
curl -X DELETE "http://localhost:8978/v1/history?id=<uuid>"

q ist optional. limit ist standardmäßig 50 und höchstens 200, offset standardmäßig 0. Ergebnisse enthalten finalen und rohen Text, ISO-8601-Zeitstempel, App-Kontext, Dauer, Sprache, Engine, Modell und Wortanzahl.

Wörterbuch

Erkennungsbegriffe beeinflussen die Transkription. Wörterbuchkorrekturen laufen danach und ersetzen passende Texte, sofern apply_corrections nicht false ist.

curl http://localhost:8978/v1/dictionary/terms

curl -X PUT http://localhost:8978/v1/dictionary/terms \
  -H "Content-Type: application/json" \
  -d '{"term_entries":[{"term":"TypeWhisper","ctc_min_similarity":0.65}],"replace":false}'

curl -X DELETE http://localhost:8978/v1/dictionary/terms \
  -H "Content-Type: application/json" \
  -d '{"term":"TypeWhisper"}'

Für einfache Begriffe genügt ein String-Array unter terms. Für Parakeet-CTC-Tuning verwendest du term_entries mit optionalem ctc_min_similarity. replace: true ersetzt alle vorhandenen Erkennungsbegriffe, andernfalls werden die Einträge zusammengeführt.

curl http://localhost:8978/v1/dictionary/corrections

curl -X PUT http://localhost:8978/v1/dictionary/corrections \
  -H "Content-Type: application/json" \
  -d '{"original":"teh","replacement":"the","caseSensitive":false}'

curl -X DELETE http://localhost:8978/v1/dictionary/corrections \
  -H "Content-Type: application/json" \
  -d '{"original":"teh"}'

Einstellungs-Backup: API und CLI

Die API verwendet dasselbe Schema wie Einstellungen > Erweitert > Backup & Restore. Der Export enthält alle unterstützten Kategorien: Workflows, Wörterbucheinträge, Snippets, Prompt-Aktionen, Profile, Hotkeys, nicht gebündelte Plugins, Verlauf, Update-Kanal und Einstellungen.

DISCOVERY="$HOME/Library/Application Support/TypeWhisper/api-discovery.json"
TYPEWHISPER_API_PORT="$(jq -r '.port' "$DISCOVERY")"
TYPEWHISPER_API_TOKEN="$(jq -r '.token' "$DISCOVERY")"

(
  settings_backup_tmp="$(mktemp ./typewhisper-settings.json.tmp.XXXXXX)" || exit
  trap 'rm -f "$settings_backup_tmp"' EXIT
  curl --fail --silent --show-error \
    "http://localhost:$TYPEWHISPER_API_PORT/v1/settings/export" \
    -H "Authorization: Bearer $TYPEWHISPER_API_TOKEN" \
    --output "$settings_backup_tmp" && \
    mv "$settings_backup_tmp" typewhisper-settings.json
) && \
curl --fail --silent --show-error -X POST \
  "http://localhost:$TYPEWHISPER_API_PORT/v1/settings/import" \
  -H "Authorization: Bearer $TYPEWHISPER_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @typewhisper-settings.json

Der Import übernimmt alle Kategorien des Dokuments nach den vorhandenen Regeln zum Zusammenführen und Überspringen. Der Ziel-Mac wird vorher nicht geleert: Workflows und Profile werden angehängt, Duplikate können übersprungen werden, belegte Hotkey-Slots bleiben erhalten, nicht verfügbare oder bereits installierte Plugins werden übersprungen und Verlauf außerhalb der Aufbewahrungsfrist des Ziel-Macs wird ausgelassen.

Import-Antwort

{
  "workflowsImported": 4,
  "dictionaryImported": 52,
  "dictionarySkipped": 3,
  "snippetsImported": 6,
  "snippetsSkipped": 1,
  "promptActionsImported": 2,
  "profilesImported": 2,
  "hotkeysApplied": 1,
  "hotkeysSkipped": 1,
  "pluginsInstalled": 2,
  "pluginsSkipped": 1,
  "pluginsRegistryFetchFailed": false,
  "historyImported": 120,
  "historySkippedByRetention": 8,
  "updateChannelApplied": true,
  "preferencesApplied": 27
}

CLI-Befehle

Installiere die CLI unter Einstellungen > Erweitert > Kommandozeilen-Tool. export schreibt das API-Backup atomar. import akzeptiert relative, absolute und mit Tilde abgekürzte Pfade. Mit --json erhältst du eine maschinenlesbare Exportbestätigung oder Importzusammenfassung.

mkdir -p ~/.config/typewhisper
typewhisper export ~/.config/typewhisper/settings.json
typewhisper import ~/.config/typewhisper/settings.json
typewhisper import ~/.config/typewhisper/settings.json --json

Ein Backup kann Transkriptionsverlauf, Prompts, App- und Website-Regeln sowie weitere persönliche Konfiguration enthalten. Prüfe es, bevor du es in ein Dotfiles-Repository eincheckst. Die Implementierung ergänzt explizite Import- und Exportbefehle, lädt aber nicht automatisch $XDG_CONFIG_HOME/typewhisper/config.toml.

Workflow-basierte Regeln

curl http://localhost:8978/v1/rules
curl -X PUT "http://localhost:8978/v1/rules/toggle?id=<uuid>"

Jeder Eintrag enthält UUID, Aktivierungszustand, Priorität, App-Bundle-IDs, URL-Muster, Sprachmodus und -Hints sowie ein optionales Übersetzungsziel. Beim Start eines Diktats mit festem Workflow verwendest du dessen Regel-UUID als workflow_id.

Legacy-Kompatibilität: /v1/profiles und /v1/profiles/toggle bleiben als exakte Aliase für ältere Integrationen verfügbar.

Diktiersteuerung

Diese Routen verwenden die systemweite Diktierpipeline und das Einfügeverhalten von TypeWhisper. start liefert eine Sitzungs-UUID, stop dieselbe UUID, damit ein Skript das Ergebnis abfragen kann.

curl -X POST http://localhost:8978/v1/dictation/start \
  -H "Content-Type: application/json" \
  -d '{"workflow_id":"<uuid>"}'

curl -X POST http://localhost:8978/v1/dictation/stop
curl http://localhost:8978/v1/dictation/status
curl "http://localhost:8978/v1/dictation/transcription?id=<uuid>"

Der Body von start ist optional. Mit workflow_id muss er einen vorhandenen aktiven Workflow benennen. TypeWhisper liefert ID und Namen des gewählten Workflows in der Startantwort zurück.

Frage /v1/dictation/transcription ab, bis status completed oder failed ist. Eine abgeschlossene Antwort enthält finalen und rohen Text sowie Zeitstempel, App-Kontext, Dauer, Sprache, Engine, Modell und Wortanzahl.

Recorder-Steuerung

Der Recorder erstellt eine gespeicherte Aufnahme und kann Mikrofon, Systemaudio oder beides erfassen. Er folgt derselben Misch-, Finalisierungs- und optionalen Transkriptionspipeline wie die Recorder-Oberfläche, ohne Text in eine andere App einzufügen.

curl -X POST "http://localhost:8978/v1/recorder/start?mic=true&system_audio=true"
curl -X POST http://localhost:8978/v1/recorder/stop
curl http://localhost:8978/v1/recorder/status
curl "http://localhost:8978/v1/recorder/session?id=<uuid>"

mic und system_audio akzeptieren true, false, 1 oder 0. Fehlende Werte übernehmen die aktuellen Recorder-Einstellungen. Mindestens eine der daraus resultierenden Quellen muss aktiv bleiben.

{
  "id": "8F8C1F45-6D03-44D2-A38C-0C4DE4F7E5F7",
  "status": "completed",
  "text": "Meeting notes from the recording.",
  "output_file": "/Users/alex/Documents/TypeWhisper Recordings/Recording.m4a"
}

Sitzungen durchlaufen recording, finalizing und completed oder failed. text entfällt bei deaktivierter oder leerer Transkription. output_file wird nach erfolgreicher Finalisierung ausgegeben, fehlgeschlagene Sitzungen enthalten error.

Fehlerantworten

Fehler verwenden ein verschachteltes JSON-Objekt error mit den Feldern code und message. Werte zuerst den HTTP-Status aus und nutze message für Details:

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API token"
  }
}