TypeWhisper
EN

HTTP API

TypeWhisper enthält eine lokale REST-API für Automatisierung und Integration mit externen Tools. In macOS 1.0 ist dies eine erweiterte Oberfläche: dokumentierte /v1/* Endpunkte sollen über 1.x hinweg stabil bleiben. Aktiviere sie unter Einstellungen > Erweitert (Standard-Port: 8978).

Hinweis: Die API ist standardmäßig deaktiviert, bindet nur an localhost und ist für lokale Automatisierung gedacht, nicht für öffentlichen Netzwerkzugriff.

Status prüfen

# Check if the API is ready

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

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

Audio transkribieren

# Send an audio file for transcription

curl -X POST http://localhost:8978/v1/transcribe \

-F "file=@recording.wav" \

-F "language=en" \

-F "target_language=de"

{
  "text": "Hello, world!",
  "language": "en",
  "duration": 2.5,
  "processing_time": 0.8,
  "engine": "whisper",
  "model": "openai_whisper-large-v3_turbo"
}

Optionale Parameter

  • language - ISO 639-1-Code (z.B. en, de). Weglassen für automatische Erkennung.
  • task - transcribe (Standard) oder translate (ins Englische, nur WhisperKit).
  • target_language - ISO 639-1-Code für die Zielsprache der Übersetzung (z.B. de, fr). Wird mit Apple Translate verwendet.

Modelle auflisten

# Get available models

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

{
  "models": [
    {
      "id": "openai_whisper-large-v3_turbo",
      "engine": "whisper",
      "ready": true
    }
  ]
}

Verlauf

# Search history

curl "http://localhost:8978/v1/history?q=meeting&limit=10&offset=0"

# Delete a history entry

curl -X DELETE "http://localhost:8978/v1/history?id=<uuid>"

Profile

# List all profiles

curl http://localhost:8978/v1/profiles

# Toggle a profile on or off

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

Diktiersteuerung

# Start dictation

curl -X POST http://localhost:8978/v1/dictation/start

# Stop dictation

curl -X POST http://localhost:8978/v1/dictation/stop

# Check dictation status

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

Fehlerantworten

Die API gibt Standard-HTTP-Statuscodes mit einem JSON-Fehlerkörper zurück:

{
  "error": "No model loaded",
  "code": "MODEL_NOT_LOADED"
}

Häufige Fehlercodes

  • 400 - Fehlende oder ungültige Dateieingabe, nicht unterstütztes Audioformat oder ungültiger Parameterwert.
  • 503 - Kein Modell ist derzeit geladen.
  • 500 - Interner Transkriptionsfehler. Prüfe die App-Logs oder den Diagnose-Export für weitere Details.