API Endpoints Reference

Complete technical reference for all Speech-to-Text API endpoints, including batch transcription, WebSocket real-time audio streaming, code snippets, and JSON response payloads.

Batch Audio Transcription

1. Universal Transcription Endpoint

The universal endpoint automatically inspects the model parameter and routes requests to the optimal recognition engine (Cipher or Lucid). This is the recommended default endpoint for all file uploads, podcasts, customer calls, and meeting transcripts.

Request Parameters (multipart/form-data)

Code Snippet: cURL

curl -X POST "https://yourvoic.com/api/v1/stt/transcribe" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@meeting_recording.mp3" \
  -F "model=cipher-fast" \
  -F "language=en" \
  -F "smart_format=true" \
  -F "response_format=verbose_json"

Code Snippet: Python (requests)

import requests

url = "https://yourvoic.com/api/v1/stt/transcribe"
headers = {"X-API-Key": "YOUR_API_KEY"}

with open("customer_call.wav", "rb") as audio_file:
    files = {"file": ("customer_call.wav", audio_file, "audio/wav")}
    data = {
        "model": "cipher-max",
        "language": "en",
        "smart_format": "true",
        "diarize": "true",
        "response_format": "verbose_json"
    }
    response = requests.post(url, headers=headers, files=files, data=data)

result = response.json()
print(f"Status: {response.status_code}")
print(f"Transcript: {result.get('text')}")

Code Snippet: Node.js (Fetch & FormData)

import fs from 'node:fs';
import FormData from 'form-data';
import fetch from 'node-fetch';

const form = new FormData();
form.append('file', fs.createReadStream('audio.mp3'));
form.append('model', 'cipher-fast');
form.append('language', 'auto');
form.append('smart_format', 'true');

const response = await fetch('https://yourvoic.com/api/v1/stt/transcribe', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    ...form.getHeaders()
  },
  body: form
});

const data = await response.json();
console.log('Transcription Text:', data.text);
console.log('Duration:', data.duration, 'seconds');

Response JSON Example (200 OK - Verbose Format)

{
  "success": true,
  "job_id": "stt_job_7a19e2bf40d34a",
  "text": "Hello, thank you for calling YourVoic support. How may I assist you today?",
  "model": "cipher-fast",
  "language": "en",
  "language_probability": 0.998,
  "duration": 5.42,
  "confidence": 0.985,
  "credits_used": 11,
  "words": [
    {"word": "Hello", "start": 0.24, "end": 0.68, "confidence": 0.992, "speaker": 0},
    {"word": "thank", "start": 0.72, "end": 0.94, "confidence": 0.987, "speaker": 0},
    {"word": "you", "start": 0.96, "end": 1.12, "confidence": 0.991, "speaker": 0},
    {"word": "for", "start": 1.14, "end": 1.28, "confidence": 0.984, "speaker": 0},
    {"word": "calling", "start": 1.30, "end": 1.64, "confidence": 0.994, "speaker": 0},
    {"word": "YourVoic", "start": 1.68, "end": 2.15, "confidence": 0.978, "speaker": 0},
    {"word": "support", "start": 2.20, "end": 2.65, "confidence": 0.991, "speaker": 0}
  ],
  "segments": [
    {
      "id": 0,
      "seek": 0,
      "start": 0.24,
      "end": 2.65,
      "text": "Hello, thank you for calling YourVoic support.",
      "tokens": [15496, 11, 1309, 291, 1541, 4820, 1129, 13],
      "temperature": 0.0,
      "avg_logprob": -0.124
    }
  ]
}

2. Direct Engine Endpoints

Dedicated low-latency endpoint pinned specifically to Cipher models (cipher-fast and cipher-max). Ensures deterministic routing without model fallback heuristics.

Direct endpoint pinned to the Lucid engine architecture (lucid-mono, lucid-multi, lucid-agent, and lucid-lite).

Real-time Streaming Endpoints

1. WebSocket Streaming Endpoint

Full-duplex WebSocket connection for low-latency live streaming transcription (under 250ms latency). Requires the api_key authentication query parameter.

Initial Client Configuration Frame (JSON)

Immediately after opening the WebSocket handshake, client sends a configuration JSON object:

{
  "action": "start",
  "encoding": "linear16",
  "sample_rate": 16000,
  "channels": 1,
  "language": "en",
  "model": "lucid-agent",
  "interim_results": true,
  "smart_format": true
}

Streaming Server Transcript Response (JSON)

Server streams interim (partial) hypotheses followed by finalized recognized sentences:

{
  "type": "transcript",
  "is_final": true,
  "text": "Welcome to YourVoic live speech transcription.",
  "confidence": 0.984,
  "start_timestamp": 0.14,
  "end_timestamp": 2.38,
  "speech_final": true
}

2. Streaming Metadata and Status

Returns health status, active concurrent streaming session quotas, and maximum session duration limits (up to 4 hours per session).

Authentication

All API endpoints validate permissions using secret API keys issued in your developer dashboard:

# HTTP Header (REST batch endpoints)
X-API-Key: yv_live_948f21903ba88e72c019

# Query parameter (WebSocket streaming endpoints)
wss://yourvoic.com:8443/api/v1/stt/realtime/stream?api_key=yv_live_948f21903ba88e72c019

Error Responses and Status Codes

When an error occurs, the API returns a structured RFC 7807 compliant JSON payload:

Error Payload Example (402 Insufficient Credits)

{
  "success": false,
  "error": {
    "code": "insufficient_credits",
    "message": "Required 360 credits for 180s audio, but your current balance is 120 credits.",
    "current_balance": 120,
    "required_credits": 360,
    "upgrade_url": "https://yourvoic.com/api/user"
  }
}

Base URLs