OpenScriber API v0.2.0

POST /api/v1/speech:batchRecognize

Submit an audio file for asynchronous transcription. Returns a jobId; poll GET /jobs/{jobId} for progress, then fetch the transcript. Server-side, the upload is decoded to 16 kHz mono WAV (mp3/mp4/m4a/ogg/wav/… accepted via ffmpeg) before inference.

Authenticates via Depends(rate_limiter) → 401/403 and 429 (rate limit, per-key pending-job cap, or daily audio quota) all apply.

Request — multipart/form-data

BatchConfig fields

Example — cURL

curl -s -X POST "https://proscribe.techon.top/api/v1/speech:batchRecognize" \
  -H "X-API-Key: sk_live_..." \
  -F "file=@audio.wav" \
  -F 'config={"engine":"whisper","model":"whisper-base","language":null,"word_timestamps":true}'

Response — 200 OK

{
  "jobId": "3f0c1d2e-...",
  "status": "QUEUED",
  "config": {"engine": "whisper", "model": "whisper-base", "language": null, "word_timestamps": true}
}

Errors: 400 no file · 401 missing key · 403 invalid key · 422 invalid config JSON · 429 rate limit / too many pending jobs / daily audio quota (Retry-After header).

GET /api/v1/speech:jobs/{jobId}

Fetch the status and metadata of one batch job.

Authenticates via Depends(rate_limiter) → 401/403 and 429 apply. Jobs are scoped to the calling key (anonymous sees all when auth is disabled).

Example — cURL

curl -s "https://proscribe.techon.top/api/v1/speech:jobs/3f0c1d2e-..." \
  -H "X-API-Key: sk_live_..."

Response — 200 OK (single JSON object)

{
  "jobId": "3f0c1d2e-...",
  "status": "COMPLETED",
  "progress": 100,
  "result_uri": "/v1/transcripts/3f0c1d2e-...",
  "requested_at": "2026-09-22T17:31:01Z",
  "started_at": "2026-09-22T17:31:02Z",
  "completed_at": "2026-09-22T17:32:10Z",
  "original_filename": "audio.wav",
  "whisper_config_json": "{\"engine\":\"whisper\",\"model\":\"whisper-base\"}",
  "selected_language": "en",
  "resolved_model": "whisper-base"
}

Errors: 401 missing key · 403 invalid key, or the job belongs to another API key · 404 job not found · 429 rate limit.

POST /api/v1/speech:jobs/{jobId}:retry

Requeue a finished/failed job using its original upload and configuration. The original audio file must still be on the server.

Authenticates via Depends(require_api_key) only — no rate limiter → no 429. Jobs are scoped to the calling key.

Example — cURL

curl -s -X POST "https://proscribe.techon.top/api/v1/speech:jobs/3f0c1d2e-...:retry" \
  -H "X-API-Key: sk_live_..."

Response — 200 OK

{"jobId": "3f0c1d2e-...", "status": "QUEUED", "retry_count": 1}

Errors: 401 missing key · 403 job belongs to another key · 404 unknown job / original audio no longer available · 409 job already QUEUED/RUNNING · 422 older job has no reusable configuration. No 429 — this route is not rate-limited.

GET /api/v1/speech:jobs/list

List batch jobs, newest first. Scoped to the calling API key (anonymous sees all when auth is disabled).

Authenticates via Depends(rate_limiter) → 401/403 and 429 apply.

Example — cURL

curl -s "https://proscribe.techon.top/api/v1/speech:jobs/list?limit=50" \
  -H "X-API-Key: sk_live_..."

Response — 200 OK (JSON objects only)

{
  "jobs": [
    {"jobId": "3f0c1d2e-...", "status": "COMPLETED", "progress": 100,
     "result_uri": "/v1/transcripts/3f0c1d2e-...", "requested_at": "2026-09-22T17:31:01Z",
     "started_at": "2026-09-22T17:31:02Z", "completed_at": "2026-09-22T17:32:10Z",
     "original_filename": "audio.wav", "whisper_config_json": "{}",
     "selected_language": "en", "resolved_model": "whisper-base"}
  ],
  "count": 1
}

Errors: 401 missing key · 403 invalid key · 429 rate limit.

GET /api/v1/speech:streams/list

List active streaming sessions. Scoped to the calling API key (anonymous sees all when auth is disabled).

Authenticates via Depends(rate_limiter) → 401/403 and 429 apply.

Example — cURL

curl -s "https://proscribe.techon.top/api/v1/speech:streams/list" \
  -H "X-API-Key: sk_live_..."

Response — 200 OK

{
  "streams": [
    {"streamId": "0a1b2c3d-...", "m3u8_url": "https://example.com/live/playlist.m3u8",
     "started_at": "2026-09-22T18:00:03Z", "model": "whisper-tiny",
     "status": "streaming", "cpu_percent": 12.0, "memory_mb": 640}
  ],
  "count": 1
}

Errors: 401 missing key · 403 invalid key · 429 rate limit.

GET /api/v1/models

Return the model capability catalogue exposed by this deployment — the source of truth for the model table below.

Authenticates via Depends(rate_limiter) → 401/403 and 429 apply.

Example — cURL

curl -s "https://proscribe.techon.top/api/v1/models" \
  -H "X-API-Key: sk_live_..."

Response — 200 OK

{"models": [
  {"id": "whisper-tiny", "engine": "whisper", "device": ["cpu"], "languages": "multilingual", "tier": "economy"},
  {"id": "whisper-base", "engine": "whisper", "device": ["cpu"], "languages": "multilingual", "tier": "balanced"},
  {"id": "vosk-model-ur", "engine": "vosk", "device": ["cpu"], "languages": "ur", "tier": "vosk-fast", "available": false}
]}

Errors: 401 missing key · 403 invalid key · 429 rate limit.

GET /api/v1/transcripts/{jobId}?format=json|srt|vtt

Retrieve the completed transcript of a job, optionally as subtitles.

Authenticates via Depends(require_api_key) only — no rate limiter → no 429. Jobs are scoped to the calling key.

If the job has not completed, the response is {"status": "...", "progress": N} instead.

Example — cURL

# JSON (default)
curl -s "https://proscribe.techon.top/api/v1/transcripts/3f0c1d2e-..." \
  -H "X-API-Key: sk_live_..."

# Subtitles
curl -s "https://proscribe.techon.top/api/v1/transcripts/3f0c1d2e-...?format=srt" \
  -H "X-API-Key: sk_live_..."
curl -s "https://proscribe.techon.top/api/v1/transcripts/3f0c1d2e-...?format=vtt" \
  -H "X-API-Key: sk_live_..."

Response — 200 OK (format: json)

{
  "jobId": "3f0c1d2e-...",
  "status": "COMPLETED",
  "model": "whisper-base",
  "language": "en",
  "language_probability": 0.98,
  "transcript": "The quick brown fox jumps over the lazy dog.",
  "segments": [
    {"start": 0.0, "end": 3.2, "text": "The quick brown fox jumps over the lazy dog.",
     "confidence": 0.96,
     "words": [{"text": "The", "start": 0.0, "end": 0.2, "confidence": 0.98}]}
  ],
  "matches": [],
  "match_counts": {},
  "alternatives": [{"transcript": "The quick brown fox jumps over the lazy dog."}]
}

Errors: 400 invalid format · 401 missing key · 403 job belongs to another key · 404 job not found. No 429 — this route is not rate-limited.

GET /api/v1/usage

Return this API key's live usage counters (self-scoped; you only ever see your own key's usage).

Authenticates via Depends(rate_limiter) → 401/403 and 429 apply.

Example — cURL

curl -s "https://proscribe.techon.top/api/v1/usage" \
  -H "X-API-Key: sk_live_..."

Response — 200 OK (auth enabled)

{
  "keyLabel": "primary",
  "batchRequests": 12,
  "streamSessions": 3,
  "audioSeconds": 45.6,
  "lastUsed": "2026-09-22T18:00:03Z"
}

When auth is disabled the response is {"enabled": false, "note": "auth is disabled — no usage is metered"} — note the enabled key only appears in that anonymous case.

Errors: 401 missing key · 403 invalid key · 429 rate limit.

WS wss://proscribe.techon.top/api/v1/speech:streamRecognize

Live transcription of an HLS stream (m3u8_url) or a raw PCM binary stream. One WebSocket per active stream.

Authentication

The key must be presented during the handshake, before the server accepts: ?api_key=<key> query param, X-API-Key header, or Authorization: Bearer <key>. Missing/invalid key → close code 1008 (the connection is rejected before accept).

Browsers cannot set WebSocket headers, so the ?api_key= query param is the practical choice in JS.

Protocol — config message first

The client MUST send a single JSON config message as the first frame within 20 seconds; otherwise the server closes with 1008 (idle). Unknown/invalid JSON → text error {"error": "invalid config"} and close.

{
  "type": "config",
  "m3u8_url": "https://example.com/live/playlist.m3u8",   // either this…
  "engine": "whisper",
  "model": "whisper-tiny",        // default "whisper-tiny" for WS
  "language": "en",               // or "auto"/null
  "word_timestamps": false,
  "stream_chunk_seconds": 8,      // optional, 2–30, default 8
  "overlap_seconds": 1,           // optional, 0 ≤ overlap < chunk, default 1
  "whisper_config": {}, "vosk_config": {}, "openrouter_config": {}
  // any other BatchConfig fields are honored too (see batchRecognize table)
}

Path A — m3u8 (HLS) streaming

The server runs ffmpeg to decode the stream to 16 kHz mono s16le PCM and emits frames per window:

Only the stable portion of each window is finalized (the trailing overlap is finalized by the following window with more context).

Path B — raw PCM binary streaming

Omit m3u8_url: send raw 16 kHz mono signed 16-bit (s16le) PCM binary frames. There is no samplerate query param — the audio is always interpreted as 16 kHz mono s16le (32 000 bytes/second).

1. Server replies {"type":"info","message":"send binary audio frames or close to finish","model":"..."}.
2. Send binary s16le PCM frames continuously (e.g. from a microphone or ffmpeg -f s16le pipe). The server buffers them into the same windows as the m3u8 path (stream_chunk_seconds / overlap_seconds from the config) and runs real speech-to-text on each window.
3. Per window the server emits the same {"type":"interim","transcript":"Processing live audio window..."} and {"type":"final","segments":[...],"matches":[...],"language":"...","processing_ms":...} frames as the m3u8 path.
4. Send the text message "close" (or close the socket) to finish; the server closes and meters the decoded audio seconds.

A connected-but-silent socket is closed after ~30 s of no frames (STREAM_WS_IDLE_TIMEOUT). Raw-PCM sessions ignore the duplicate-URL rule (each mic/source is independent) but still count against per-key and global stream caps. This is what powers the "Live microphone" mode in the test console.

Example — JavaScript (browser)

const key = "sk_live_...";
const ws = new WebSocket(
  "wss://proscribe.techon.top/api/v1/speech:streamRecognize?api_key=" + encodeURIComponent(key)
);
ws.onopen = () => ws.send(JSON.stringify({
  type: "config",
  m3u8_url: "https://example.com/live/playlist.m3u8",
  model: "whisper-tiny",
  language: "en",
  word_timestamps: false,
  stream_chunk_seconds: 8,
  overlap_seconds: 1
}));
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === "final") console.log(JSON.stringify(msg, null, 2));
  if (msg.type === "error") console.error(msg);
};

Example — Bash (websocat + ffmpeg)

# m3u8 path
printf '%s' '{"type":"config","m3u8_url":"https://example.com/live/playlist.m3u8","model":"whisper-tiny","language":"en","stream_chunk_seconds":8,"overlap_seconds":1}' \
  | websocat -H "X-API-Key: sk_live_..." "wss://proscribe.techon.top/api/v1/speech:streamRecognize"

# raw PCM path (16 kHz mono s16le, no samplerate param)
ffmpeg -re -i audio.wav -ar 16000 -ac 1 -f s16le - 2>/dev/null \
  | websocat -H "X-API-Key: sk_live_..." "wss://proscribe.techon.top/api/v1/speech:streamRecognize" \
    --text '{"type":"config"}'

Close codes you may see: 1008 missing/invalid key, or no config within 20 s · 1013 per-key/global stream cap, duplicate stream, or daily stream-session quota · 1000/normal on clean finish.