Vowise
Developers

Use API Keys, OpenAI-Compatible STT, and Shortcuts

Connect Orca, Paseo, Open WebUI, Obsidian, Shortcuts, and any OpenAI Whisper-compatible tool to Vowise STT, Custom Dictionary, and AI polishing.

Audience
Developers and power users wiring Vowise into AI coding tools, chat clients, note apps, and Shortcuts.
Time
10 minutes
Level
Advanced

Scenario

Start with the workflow this guide is designed for before moving into the steps.

As a developer or power user, I want to point my favorite AI clients (like Orca, Paseo, Open WebUI, or Obsidian) to Vowise's OpenAI-compatible STT endpoint so every voice input benefits from Vowise ASR, my cloud Custom Dictionary, and AI polishing.

You can configure `https://api.vowise.com/v1` in any OpenAI-compatible client, choose between `vowise-pro` and `vowise-raw`, and keep your API keys secure.

Steps

1

Create or locate your Vowise API key

Open Vowise Settings → API Keys to create a personal key (`vowise_...`). The server automatically resolves your account and cloud Custom Dictionary from this Bearer token.

The key starts with `vowise_` and is stored outside git repos.
Your technical terms (e.g., Orca, Paseo, Kubernetes) are added to your Vowise Custom Dictionary.
2

Verify the OpenAI-compatible `/v1/audio/transcriptions` endpoint

Vowise provides both the native `POST /transcribe` endpoint and the standard OpenAI Whisper-compatible `POST /v1/audio/transcriptions` endpoint under Base URL `https://api.vowise.com/v1`.

You tested `vowise-pro` (ASR + Cloud Dictionary + AI Polishing) or `vowise-raw` (ASR + Cloud Dictionary).
You verified a quick test request via `/api-reference` or `curl`.
3

Connect Orca, Paseo, Open WebUI, Obsidian, or Shortcuts

In your target app's Speech-to-Text (STT) or OpenAI Audio settings, set Base URL to `https://api.vowise.com/v1`, paste your `vowise_...` API key, and set Model to `vowise-pro` (or `vowise-raw`).

Voice dictation in your tool returns polished text with custom dictionary terms corrected.
The workflow does not print the API key in public logs or screenshots.

OpenAI-Compatible STT & Third-Party Ecosystem Guide

Any application or SDK that supports OpenAI's `/v1/audio/transcriptions` (Whisper API) works with Vowise out of the box by changing only the Base URL and API Key.

1. Universal Connection Parameters & Models

Use the following standard OpenAI Audio parameters across all compatible clients:

ParameterRecommended ValueNotes
Base URLhttps://api.vowise.com/v1Automatically routes to POST /v1/audio/transcriptions
API Keyvowise_YOUR_API_KEYResolves your Vowise account and cloud Custom Dictionary
Model (Polished)vowise-proASR + Cloud Dictionary + AI Polishing (removes filler words & formats punctuation)
Model (Fast Raw)vowise-rawASR + Cloud Dictionary only (skips LLM polishing for lowest latency)
Model (Compat)whisper-1Automatically mapped to vowise-pro for clients with hardcoded model names
  • Supports wav, mp3, m4a, mp4, webm, ogg, and flac audio uploads up to 100 MB.
  • Supports both `response_format=json` (`{"text": "..."}`) and `response_format=text`.

2. Supported Third-Party Tools Matrix

All tools below use standard OpenAI Audio Transcriptions and can be wired to Vowise in under a minute:

Tool / ClientCategoryWhere to ConfigureRecommended Model
OrcaAI Coding & Multi-Agent~/.orca/speech-config.jsonvowise-pro
PaseoAI Coding & Voice CLI~/.paseo/config.jsonvowise-pro
Open WebUISelf-Hosted AI HubAdmin Settings → Audio → STT Engine: OpenAIvowise-pro
LobeChat / Cherry Studio / ChatBoxDesktop & Web AI ChatSettings → Speech Service / OpenAI Proxy URLvowise-pro
Obsidian (Whisper Plugin)Knowledge Base & NotesPlugin Settings → API URL: https://api.vowise.com/v1/audio/transcriptionswhisper-1 / vowise-pro
Whispering / VoiceInk / SuperwhisperGlobal Desktop DictationCustom OpenAI-Compatible Provider (`https://api.vowise.com/v1`)vowise-pro or vowise-raw
iOS Shortcuts / RaycastMobile & macOS AutomationHTTP POST multipart/form-data to /v1/audio/transcriptionsvowise-pro
  • Check whether the client asks for the Base URL (`https://api.vowise.com/v1`) or the full endpoint URL (`https://api.vowise.com/v1/audio/transcriptions`).

3. Step-by-Step: Connect Orca & Paseo (Desktop + Mobile Web)

For **Orca**, create or edit `~/.orca/speech-config.json` on the machine running the Orca daemon. Both the desktop composer and the mobile web composer will route voice recordings through Vowise:

{
  "apiKey": "vowise_YOUR_API_KEY",
  "baseUrl": "https://api.vowise.com/v1",
  "model": "vowise-pro",
  "language": "zh"
}

For **Paseo**, configure `providers.openai` and `features.dictation` inside `~/.paseo/config.json`:

{
  "providers": {
    "openai": {
      "apiKey": "vowise_YOUR_API_KEY",
      "baseUrl": "https://api.vowise.com/v1"
    }
  },
  "features": {
    "dictation": {
      "enabled": true,
      "stt": {
        "provider": "openai",
        "model": "vowise-pro",
        "language": "zh"
      }
    }
  }
}
  • Orca reads `~/.orca/speech-config.json` dynamically on each voice transcription request—no restart required when switching between `vowise-pro` and `vowise-raw`.
  • When you tap the stop button on mobile or desktop, the composer displays a loading spinner until the polished Vowise transcript is inserted.

4. cURL & Official OpenAI SDK Examples

Test from the terminal with `curl` or use the official OpenAI Python/Node SDKs without installing any custom client:

curl -X POST "https://api.vowise.com/v1/audio/transcriptions" \
  -H "Authorization: Bearer vowise_YOUR_API_KEY" \
  -F "[email protected]" \
  -F "model=vowise-pro" \
  -F "language=zh"
from openai import OpenAI

client = OpenAI( base_url="https://api.vowise.com/v1", api_key="vowise_YOUR_API_KEY", )

with open("sample.wav", "rb") as audio: tx = client.audio.transcriptions.create( model="vowise-pro", file=audio, language="zh", ) print(tx.text) ```

  • Pass an optional `prompt` field to provide extra context or hints for a specific recording.

5. Secret handling rules

Docs can teach the request shape, but examples should use placeholders instead of real secrets, reusable passwords, or private URLs.

  • Use placeholders in docs and screenshots.
  • Keep real keys in local secret stores (`chmod 600`) or server-side config.
  • Rotate a key immediately in Vowise Settings if it appears in a public recording.

Connected feature paths

This tutorial should not dead-end. These are the natural next features and workflows it connects to.