Live Translation

VALSEA provides a real-time speech-to-text and translation API via WebSocket — stream audio in one language and receive both the original transcript and a live translation into your target language.

Connection

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

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. If speaker diarization is also enabled for the session, the final session cost is 4x the normal realtime credit cost.

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, target 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 — transcript.final includes the translation once target_language is set.
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 in the original language. This can change as more audio arrives. Partials are never translated.
• transcript.final: stable text for a completed segment — translated, if target_language was requested. 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",
  "target_language": "spanish",
  "noise_suppression": "off"
}

When target_language is set and differs from the input language, transcript.final.text is translated to that target language, and rawText holds the original transcript. Partial transcripts are never translated. Supported translation targets are english, chinese, japanese, korean, vietnamese, thai, french, spanish, german, russian, indonesian, malay, filipino, tamil, khmer, and lao.

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, in the original language (low latency, may change).

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

transcript.final

Finalized text for a speech segment. Without translation:

{
  "type": "transcript.final",
  "text": "The quick brown fox jumps over the lazy dog while the market",
  "rawText": "The quick brown fox jumps over the lazy dog while the market",
  "isFinal": true,
  "timestampMs": 3765
}

With target_language set — real, captured output translating English to Spanish:

{
  "type": "transcript.final",
  "text": "El rápido zorro marrón salta sobre el perro perezoso mientras el mercado",
  "rawText": "The quick brown fox jumps over the lazy dog while the market",
  "isFinal": true,
  "timestampMs": 3765,
  "translated": true,
  "sourceLanguage": "english",
  "targetLanguage": "spanish"
}

error

Sent when an error occurs.

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

Real example — invalid translation target. Captured during testing: "chinese" normalizes internally to "chinese-mandarin", which isn't in the allowed target list, so the session ends:

{
  "type": "error",
  "code": "INVALID_TRANSLATION_TARGET",
  "message": "Translation target language 'chinese-mandarin' is not supported"
}

{
  "type": "session.ended",
  "reason": "invalid_translation_target",
  "error": "Translation target language 'chinese-mandarin' is not supported"
}

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/translate', {
  headers: { 'X-API-Key': 'YOUR_KEY' },
});

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

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('Original:', msg.rawText);
    console.log('Translated:', 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