API Reference

Overview

Real-time text-to-speech synthesis API. Send text, receive streaming PCM audio chunks.

After connecting and receiving SessionReady, send your text as a binary InteractionInput message followed by a JSON EndInteraction. The server synthesizes speech and streams back audio chunks as binary InteractionResponse messages. The final chunk has is_final set to true.

Production deployments: Connect to the real-time WebSocket API from a backend server to keep your API key secure.

---

How It Works

1. Connect to the WebSocket endpoint with your API key and config ID

2. Receive SessionReady — the server has allocated inference resources for your session

3. Send text as a binary InteractionInput message (payload type 0 for text)

4. Send EndInteraction (JSON) to signal that input is complete and synthesis should begin

5. Receive audio chunks — binary InteractionResponse messages containing PCM int16 audio at 24 kHz

6. Detect completion — the last response has is_final: true

Audio Output Format

Property	Value
Format	PCM signed 16-bit integers (little-endian samples)
Sample rate	24,000 Hz
Channels	1 (mono)
Bits per sample	16

---

Connection Flow

---

WebSocket Handshake

Open WebSocket connection

get

Connect to the WebSocket endpoint providing an API key in the Authorization header and a config_id query parameter. The server upgrades the connection to WebSocket. After sending SessionReady, the server waits for text input.

Recommended WebSocket settings:

• open_timeout: None (model loading may take time on cold start)

• ping_timeout: None

Authorizations

ApiKeyAuth

AuthorizationstringRequired

Raw API key (no Bearer prefix).

Query parameters

config_idstringRequired

Configuration ID for the TTS voice, created via API or in the Oris Voice tab of the dashboard.

Header parameters

AuthorizationstringRequired

Your raw API key. No Bearer prefix.

Example: your-api-key

Responses

101

WebSocket upgrade successful. After the upgrade, the server sends a SessionReady JSON message and waits for text input.

application/json

401

Unauthorized — invalid or missing API key.

application/json

get

/

HTTPcURLJavaScriptPython

GET /realtime/?config_id=text HTTP/1.1
Authorization: your-api-key
Accept: */*

{
  "type": "sessionReady",
  "payload": {
    "trace_id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "success",
    "load": 0.35,
    "timestamp": 1723567893000,
    "parameters": {
      "sample_rate": 24000,
      "channels": 1,
      "bits_per_sample": 16
    }
  }
}

---

Message Format

Mixed message types: The server sends both JSON (text) and binary messages on the same WebSocket connection. Your client must check the WebSocket frame type to distinguish them:

• Text frames (JSON): SessionReady, EndInteraction, CancelInteraction, ErrorResponse

• Binary frames: InteractionInput, InteractionResponse

Byte order: All multi-byte integer fields in binary messages use network byte order (big-endian).

---

Messages Reference

Server -> Client Messages

Client -> Server Messages

---

Message Details

InteractionInput (Client -> Server, Binary)

Binary message for sending text to the server.

Binary structure:

[1 byte ]  Payload type      — uint8, 0 for text
[8 bytes]  Timestamp          — uint64, milliseconds since Unix epoch
[4 bytes]  Params size        — uint32, byte length of the JSON params block (0 if no params)
[N bytes]  Params JSON        — UTF-8 encoded JSON (only present if params size > 0)
[M bytes]  Text payload       — UTF-8 encoded text to synthesize

Header fields use big-endian byte order. In Python: struct.pack('!BQI', payload_type, timestamp, params_size).

Text requirements:

Property	Value
Encoding	UTF-8
Payload type	0 (text)
Max message size	512 KB (entire binary message including header)

Example:

import struct, time

def build_text_message(text, params=None):
    """Build a binary InteractionInput message for text."""
    payload = text.encode("utf-8")
    params_bytes = b""
    if params:
        import json
        params_bytes = json.dumps(params).encode("utf-8")
    header = struct.pack('!BQI', 0, int(time.time() * 1000), len(params_bytes))
    return header + params_bytes + payload

---

InteractionResponse (Server -> Client, Binary)

Binary message containing an audio chunk. The server streams these after receiving text input and EndInteraction.

Binary structure:

[1 byte  ]  Is final flag     — uint8, 1 = last chunk for this interaction, 0 = more coming
[16 bytes]  Interaction ID     — UUID bytes (big-endian)
[8 bytes ]  Timestamp          — uint64, milliseconds since Unix epoch
[4 bytes ]  Usage              — uint32, usage metric for this response
[4 bytes ]  Index              — uint32, chunk index
[4 bytes ]  Num payloads       — uint32, number of payload entries that follow

For each payload entry:
  [4 bytes]  Data size          — uint32, byte length of the payload data
  [1 byte ]  Payload type       — uint8, 1 = audio
  [N bytes]  Payload data       — raw PCM int16 audio bytes

All multi-byte integers are big-endian. In Python: struct.unpack('!B16sQIII', header_bytes) for the main header, struct.unpack('!IB', entry_bytes) for each payload entry.

Payload types:

Type	Format	Description
1 (audio)	PCM int16, 24 kHz mono	Streaming audio chunk (variable size)

Parsing example:

import struct, uuid

HEADER_FMT = '!B16sQIII'
HEADER_SIZE = struct.calcsize(HEADER_FMT)   # 37 bytes
ENTRY_FMT = '!IB'
ENTRY_SIZE = struct.calcsize(ENTRY_FMT)     # 5 bytes

def parse_response(data):
    is_final, uuid_bytes, timestamp, usage, index, num_payloads = \
        struct.unpack(HEADER_FMT, data[:HEADER_SIZE])

    offset = HEADER_SIZE
    audio_chunks = []

    for _ in range(num_payloads):
        size, ptype = struct.unpack(ENTRY_FMT, data[offset:offset + ENTRY_SIZE])
        offset += ENTRY_SIZE
        if ptype == 1 and size > 0:  # audio
            audio_chunks.append(data[offset:offset + size])
        offset += size

    return {
        'is_final': bool(is_final),
        'interaction_id': str(uuid.UUID(bytes=uuid_bytes)),
        'index': index,
        'audio_chunks': audio_chunks,
    }

---

EndInteraction vs CancelInteraction

Message	Purpose	Server behavior	Use case
EndInteraction	Graceful finish	Completes synthesis, sends remaining chunks with last marked is_final: true	Normal completion after sending text
CancelInteraction	Immediate stop	Stops synthesis, discards remaining audio	User interruption or abort

---

ErrorResponse (Server -> Client, JSON)

Plain text errors: In some error conditions (e.g., no backend servers available), the server may send a plain text message instead of a structured JSON ErrorResponse. Your client should handle non-JSON text messages gracefully.

Error codes:

Code	Description
AUTH_FAILED	Invalid API key
UNAUTHORIZED	Caller lacks permission
MISSING_CONFIG_ID	config_id query parameter not provided
INVALID_MESSAGE	Malformed or unsupported message payload
INVALID_HEADERS	Missing or invalid headers
MODEL_NOT_FOUND	Config ID not found or invalid
BACKEND_UNAVAILABLE	No healthy inference backend available
RATE_LIMITED	Too many requests
TIMEOUT	Operation exceeded processing time
CANCELLED	Interaction cancelled by client
INTERNAL_ERROR	Unexpected server error
FRAME_SIZE_EXCEEDED	Message exceeded 512 KB limit

---

Rate Limits & Constraints

Constraint	Value
Max message size	512 KB per message
Max generation length	~30 seconds per interaction (360 tokens at 12 Hz)

Exceeding limits results in an ErrorResponse with the appropriate code.

---

Best Practices

Text Input

• Send the full text in a single InteractionInput message, then immediately send EndInteraction

• The model handles sentence segmentation and streaming internally

• For very long texts, consider splitting into sentences and making separate requests

Streaming Playback

• Process audio chunks as they arrive for lowest perceived latency

• Buffer a small amount (2--3 chunks) before starting playback to absorb network jitter

• The server generates audio faster than realtime, so chunks will arrive ahead of playback

Error Handling

• Handle both JSON ErrorResponse messages and plain text error strings

• Implement exponential backoff for reconnection

• Check the SessionReady message before sending any input

---

Complete Example

import asyncio
import json
import struct
import time
import wave
import os

import websockets
from dotenv import load_dotenv

load_dotenv()

API_KEY = os.getenv("OJIN_API_KEY", "")
CONFIG_ID = os.getenv("OJIN_CONFIG_ID", "")
WS_URL = f"wss://models.ojin.ai/realtime?config_id={CONFIG_ID}"

SAMPLE_RATE = 24000

def build_text_message(text):
    """Build a binary InteractionInput for text payload."""
    header = struct.pack('!BQI', 0, int(time.time() * 1000), 0)
    return header + text.encode('utf-8')

def parse_response(data):
    """Parse a binary InteractionResponse."""
    fmt = '!B16sQIII'
    hdr_size = struct.calcsize(fmt)
    is_final, _, _, _, _, num_payloads = struct.unpack(fmt, data[:hdr_size])

    offset = hdr_size
    audio = []
    for _ in range(num_payloads):
        size, ptype = struct.unpack('!IB', data[offset:offset + 5])
        offset += 5
        if ptype == 1 and size > 0:
            audio.append(data[offset:offset + size])
        offset += size

    return bool(is_final), audio

async def main():
    headers = websockets.Headers()
    headers["Authorization"] = API_KEY

    async with websockets.connect(
        WS_URL,
        additional_headers=headers,
        open_timeout=None,
        ping_timeout=None,
    ) as ws:
        # 1. Wait for session ready
        while True:
            msg = await ws.recv()
            if isinstance(msg, str):
                parsed = json.loads(msg)
                if parsed.get("type") == "sessionReady":
                    print(f"Session ready (trace_id: {parsed['payload'].get('trace_id')})")
                    break
                if parsed.get("type") == "errorResponse":
                    raise RuntimeError(parsed["payload"]["message"])

        # 2. Send text + end interaction
        text = "Hello! This is a demonstration of Ojin Oris Voice text to speech."
        await ws.send(build_text_message(text))
        await ws.send(json.dumps({
            "type": "endInteraction",
            "payload": {"timestamp": int(time.time() * 1000)},
        }))
        print(f"Sent text ({len(text)} chars), waiting for audio...")

        # 3. Receive audio chunks
        audio_data = []
        chunk_count = 0
        t0 = time.monotonic()

        while True:
            msg = await ws.recv()
            if isinstance(msg, str):
                parsed = json.loads(msg)
                if parsed.get("type") == "errorResponse":
                    raise RuntimeError(parsed["payload"]["message"])
                continue

            is_final, chunks = parse_response(msg)
            audio_data.extend(chunks)
            chunk_count += len(chunks)

            if is_final:
                break

        elapsed = time.monotonic() - t0

        # 4. Write WAV file
        pcm = b"".join(audio_data)
        duration = len(pcm) / (SAMPLE_RATE * 2)
        output_path = f"tts-output-{int(time.time())}.wav"

        with wave.open(output_path, "wb") as wf:
            wf.setnchannels(1)
            wf.setsampwidth(2)
            wf.setframerate(SAMPLE_RATE)
            wf.writeframes(pcm)

        print(f"Saved {output_path}")
        print(f"  Chunks: {chunk_count}")
        print(f"  Duration: {duration:.2f}s")
        print(f"  Elapsed: {elapsed:.2f}s")
        if duration > 0:
            print(f"  RTF: {elapsed / duration:.2f}x")

asyncio.run(main())

---

Troubleshooting

Connection Issues

• Verify API key and config ID

• Check that the config exists in the dashboard

• Ensure network allows WebSocket connections (port 443)

• The Authorization header uses the raw API key (no Bearer prefix)

No Audio Received

• Confirm you received SessionReady before sending text

• Make sure you send EndInteraction after the text input — synthesis does not start until the server receives it

• Check message size is under 512 KB

Audio Quality Issues

• Verify the output is written as 24 kHz, 16-bit mono WAV

• Check the language parameter matches your input text, or use "Auto"

• For voice cloning, ensure the reference audio is clean and at least 5 seconds long

Unexpected Silence or Truncation

• Check max_new_tokens — the default (360) caps output at ~30 seconds

• If the text is very long, consider splitting into smaller segments

---