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
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.
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`.
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`).
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:
| Parameter | Recommended Value | Notes |
|---|---|---|
| Base URL | https://api.vowise.com/v1 | Automatically routes to POST /v1/audio/transcriptions |
| API Key | vowise_YOUR_API_KEY | Resolves your Vowise account and cloud Custom Dictionary |
| Model (Polished) | vowise-pro | ASR + Cloud Dictionary + AI Polishing (removes filler words & formats punctuation) |
| Model (Fast Raw) | vowise-raw | ASR + Cloud Dictionary only (skips LLM polishing for lowest latency) |
| Model (Compat) | whisper-1 | Automatically 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 / Client | Category | Where to Configure | Recommended Model |
|---|---|---|---|
| Orca | AI Coding & Multi-Agent | ~/.orca/speech-config.json | vowise-pro |
| Paseo | AI Coding & Voice CLI | ~/.paseo/config.json | vowise-pro |
| Open WebUI | Self-Hosted AI Hub | Admin Settings → Audio → STT Engine: OpenAI | vowise-pro |
| LobeChat / Cherry Studio / ChatBox | Desktop & Web AI Chat | Settings → Speech Service / OpenAI Proxy URL | vowise-pro |
| Obsidian (Whisper Plugin) | Knowledge Base & Notes | Plugin Settings → API URL: https://api.vowise.com/v1/audio/transcriptions | whisper-1 / vowise-pro |
| Whispering / VoiceInk / Superwhisper | Global Desktop Dictation | Custom OpenAI-Compatible Provider (`https://api.vowise.com/v1`) | vowise-pro or vowise-raw |
| iOS Shortcuts / Raycast | Mobile & macOS Automation | HTTP POST multipart/form-data to /v1/audio/transcriptions | vowise-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 OpenAIclient = 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.
Create a custom dictionary
Protect names, brands, acronyms, and domain terms during transcription.
Troubleshoot recording, network & transcription issues
Fix Vowise recording, network, upload, and transcription problems without losing a retained recording. Learn what is saved locally, what still needs connectivity, and how to retry safely.
Start with Vowise
Pick the right first workflow: record, import, review, or automate.