Live Transcription

VALSEA provides a real-time, transcription-only speech-to-text API via WebSocket, allowing you to stream audio and receive transcriptions with low latency. This endpoint never translates — it's the leanest, fastest option when all you need is text.

Connection

Endpoint: wss://api.valsea.ai/v1/realtime/asr

Authentication

You must authenticate the WebSocket connection by passing your API key in the HTTP headers during the handshake.

Headers:

• Authorization: Bearer YOUR_API_KEY (Recommended)
• X-API-Key: YOUR_API_KEY (Supported)

Paid Rate-Limit Bypass

If you need to exceed the realtime connection RPM limit for a session, you can bypass the rate-limit check by sending one of these opt-in flags during the WebSocket handshake:

• Header: X-Bypass-Rate-Limit: true
• Query parameter: bypass_rate_limit=true
• Query parameter: bypassRateLimit=true

Bypass applies only to the per-organization rate-limit check. Authentication, credit checks, and session billing still apply. RTT sessions using this bypass are billed at 2x the normal realtime credit cost. The initial session.created event includes rateLimitBypass: true and billingMultiplier: 2 when bypass is active.

Message Flow

1. Connect: Client establishes WebSocket connection.
2. Session Created: Server sends session.created event.
3. Start Session: Client sends session.start to configure language and model.
4. Stream Audio: Client sends audio.append messages with base64-encoded PCM16 audio chunks.
5. Receive Transcripts: Server streams transcript.partial and transcript.final events.
6. Commit Audio: Client sends audio.commit when a user stops speaking (optional/VAD dependent).
7. Stop Session: Client sends session.stop to end the session.

Partial vs Final (Important)

RTT emits two transcript event types for each utterance:

• transcript.partial: low-latency, in-progress text. This can change as more audio arrives.
• transcript.final: stable text for a completed segment. Treat this as the committed result.

Recommended client behavior:

1. Keep a temporary currentPartial string for transcript.partial.
2. Append only transcript.final to your persisted transcript history.
3. Clear currentPartial when you receive a matching transcript.final.

Client Messages

session.start

Initialize the session with configuration.

{
  "type": "session.start",
  "model": "valsea-rtt",
  "hint_text": "Optional context or vocabulary",
  "enable_correction": true,
  "language": "auto",
  "noise_suppression": "off"
}

audio.append

Send audio data.

{
  "type": "audio.append",
  "audio": "BASE64_ENCODED_PCM16_DATA"
}

• Format: Raw PCM 16-bit, 16kHz (recommended), mono.
• Encoding: Base64 string.

You may also send raw binary PCM16 frames directly over the WebSocket. Binary frames are treated as audio.append messages by the server.

audio.commit

Signal the end of a speech segment (e.g., VAD triggered silence).

{
  "type": "audio.commit"
}

session.stop

End the session gracefully.

{
  "type": "session.stop"
}

Server Messages

session.created

Sent immediately upon connection.

{
  "type": "session.created",
  "sessionId": "rtt_...",
  "supportedModels": ["valsea-rtt"]
}

session.ready

Sent when the backend engine is connected and ready to receive audio.

{
  "type": "session.ready",
  "sessionId": "rtt_...",
  "engine": "valsea-7"
}

transcript.partial

Intermediate transcription results (low latency, may change).

{
  "type": "transcript.partial",
  "text": "The quick brown",
  "isFinal": false,
  "timestampMs": 1888
}

transcript.final

Finalized text for a speech segment. On this endpoint, text and rawText are always identical — translation fields (translated, sourceLanguage, targetLanguage) never appear here.

{
  "type": "transcript.final",
  "text": "The quick brown fox jumps over the lazy dog while the market opens at 9.30 in the morning.",
  "rawText": "The quick brown fox jumps over the lazy dog while the market opens at 9.30 in the morning.",
  "isFinal": true,
  "timestampMs": 6328
}

error

Sent when an error occurs.

{
  "type": "error",
  "code": "INVALID_MESSAGE",
  "message": "Failed to parse message"
}

Error codes on this endpoint

Event Handling Pattern

Use this pattern to avoid duplicated or unstable transcript content:

let currentPartial = '';
const finalSegments = [];

ws.on('message', (raw) => {
  const msg = JSON.parse(raw);

  if (msg.type === 'transcript.partial') {
    currentPartial = msg.text || '';
  }

  if (msg.type === 'transcript.final') {
    finalSegments.push(msg.text || '');
    currentPartial = '';
  }
});

Example (Node.js)

const WebSocket = require('ws');
const fs = require('fs');

const ws = new WebSocket('wss://api.valsea.ai/v1/realtime/asr', {
  headers: { 'X-API-Key': 'YOUR_KEY' },
});

ws.on('open', () => {
  ws.send(
    JSON.stringify({
      type: 'session.start',
      model: 'valsea-rtt',
      language: 'auto',
    }),
  );
});

ws.on('message', (data) => {
  const msg = JSON.parse(data);

  if (msg.type === 'session.ready') {
    const audioStream = fs.createReadStream('audio.raw');
    audioStream.on('data', (chunk) => {
      ws.send(
        JSON.stringify({
          type: 'audio.append',
          audio: chunk.toString('base64'),
        }),
      );
    });
  } else if (msg.type === 'transcript.final') {
    console.log('Final:', msg.text);
  }
});

Model Selection Guide

Default: Auto-Detect

Use language: "auto" to automatically detect and transcribe speech across 100+ languages, with built-in support for code-switching — the language can change mid-conversation (or mid-sentence) without losing accuracy.

{
  "language": "auto"
}

Best for:

• Multi-language or unknown input
• Conversations where speakers switch languages mid-utterance
• Global applications
• Fast setup with minimal tuning

For a Fixed Language

If you already know the language being spoken, set it explicitly for the most consistent routing:

{
  "model": "valsea-rtt",
  "language": "singlish"
}

List of Languages