CodeVox Local API

CodeVox can run a small HTTP server on your Mac that transcribes audio entirely on-device. It is wire-compatible with OpenAI’s Whisper transcription API, so most existing clients work by pointing their base URL at localhost. No audio ever leaves your machine.

The full contract is published as an OpenAPI 3.1 spec.

Quickstart

1. In CodeVox, open the menu bar → Local API… and toggle Enable local API. It binds to 127.0.0.1:5273 by default.
2. On loopback the transcription endpoint needs no token. (A token is required for LAN access and for control verbs. Generate one in the same Settings pane.)
3. Transcribe a file:

curl http://127.0.0.1:5273/v1/audio/transcriptions \
  -F file=@meeting.m4a \
  -F response_format=text

OpenAI client compatibility

Point any OpenAI client at the local server. The model name is mapped to codevox-parakeet; an API key is only checked when you’ve set a token.

Python

from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:5273/v1", api_key="not-needed-on-loopback")

with open("meeting.m4a", "rb") as f:
    result = client.audio.transcriptions.create(model="codevox-parakeet", file=f)
print(result.text)

Node

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({ baseURL: "http://127.0.0.1:5273/v1", apiKey: "not-needed-on-loopback" });

const result = await client.audio.transcriptions.create({
  model: "codevox-parakeet",
  file: fs.createReadStream("meeting.m4a"),
});
console.log(result.text);

Response formats

Pass response_format = json (default), text, srt, vtt, or verbose_json (adds segment and word timestamps). model, language, temperature, and prompt are accepted; temperature/prompt are no-ops (greedy decode).

codevox CLI

A thin CLI ships inside the app bundle. Symlink it onto your PATH:

ln -sf "/Applications/CodeVox.app/Contents/Resources/codevox" /usr/local/bin/codevox

codevox status                 # is the API reachable?
codevox transcribe meeting.m4a # prints the transcript
codevox events                 # tail the live event stream
# Config via env: CODEVOX_PORT, CODEVOX_TOKEN

Event stream (SSE)

Subscribe to live transcription events over Server-Sent Events. The stream carries partials and finals from both hotkey dictation and API jobs:

curl -N http://127.0.0.1:5273/v1/events

# data: {"text":"hello world","isFinal":false,"source":"hotkey","timestamp":...}
# data: {"text":"hello world.","isFinal":true,"source":"hotkey","timestamp":...}

Supported audio & limits

• Decoded with AVFoundation: wav, mp3, m4a/aac, aiff, caf, mp4/mov audio.
• Not supported (day one): webm/opus, ogg, flac. These return a clear 400.
• Max upload 25 MB; max decoded duration 10 minutes.
• When the recognizer is saturated, requests return 429 with a Retry-After header rather than blocking.

Security model

• Loopback (default): the transcription/compute endpoints work without a token.
• LAN access (opt-in): requires at least one token; every request must send Authorization: Bearer <token>. LAN + no token is not allowed.
• Control verbs (text injection, mic capture) always require a valid token, even on loopback.
• Tokens are generated in the app, shown once, stored hashed in the Keychain, and individually revocable.

Licensing

The local API is part of CodeVox and works during the 7-day trial and for licensed users. If the trial expires or you sign out, the API stops serving and requests return a clear licensing error. API transcriptions count toward your usage just like hotkey dictation. See pricing.