TypeWhisper
DE

HTTP API

TypeWhisper includes a local REST API for automation and integration with external tools. In macOS 1.0, this is an advanced surface: documented /v1/* endpoints are intended to remain stable across 1.x. Enable it in Settings > Advanced (default port: 8978).

Note: The API is disabled by default, binds to localhost only, and is designed for local automation rather than public network access.

Check Status

# 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
}

Transcribe Audio

# 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"
}

Optional Parameters

  • language - ISO 639-1 code (e.g., en, de). Omit for auto-detection.
  • task - transcribe (default) or translate (to English, WhisperKit only).
  • target_language - ISO 639-1 code for translation target language (e.g., de, fr). Used with Apple Translate.

List Models

# Get available models

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

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

History

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

Profiles

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

Dictation Control

# 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

Error Responses

The API returns standard HTTP status codes with a JSON error body:

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

Common Error Codes

  • 400 - Missing or invalid file input, unsupported audio format, or invalid parameter value.
  • 503 - No model is currently loaded.
  • 500 - Internal transcription error. Check the app's logs or diagnostics export for more detail.