Skip to main content

Realtime Speech-to-Text - Getting Started

Before using the Realtime Speech-to-Text service, you need to ensure the service is active. The service automatically scales down after 30-60 minutes of inactivity to optimize resources.

Step 1: Check Service Status​

Endpoint: GET /v4/realtime/status

Check if the realtime service is currently active before attempting to use it.

Request​

Headers​

HeaderValueRequired
AuthorizationBearer {API_KEY}Yes

Response​

{
  "status": "ready" | "scaled_down" | "starting",
  "message": "Human-readable status message",
  "ready": true | false,
  "endpoint": "wss://realtime.scriptix.io"
}

Status Values​

  • ready - Service is active and ready to accept connections
  • scaled_down - Service is not running, call /initialize to start it
  • starting - Service is currently starting up

Step 2: Initialize Service (if needed)​

If the status shows ready: false, you need to initialize the service.

Endpoint: POST /v4/realtime/initialize

This endpoint starts the realtime service. Note: Initialization takes 1-5 minutes.

Request​

Headers​

HeaderValueRequired
AuthorizationBearer {API_KEY}Yes

Response​

{
  "status": "ready",
  "message": "Realtime service is ready for connections",
  "ready": true,
  "endpoint": "wss://realtime.scriptix.io"
}

Step 3: Poll Status Until Ready​

After calling /initialize, poll the /status endpoint every 5-10 seconds until ready: true.

Example Workflow​

Python​

import requests
import time

API_BASE = "https://api.scriptix.io"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# Step 1: Check status
response = requests.get(f"{API_BASE}/v4/realtime/status", headers=HEADERS)
status = response.json()

# Step 2: Initialize if not ready
if not status["ready"]:
    print("Service is not active. Initializing...")
    requests.post(f"{API_BASE}/v4/realtime/initialize", headers=HEADERS)

    # Step 3: Poll until ready
    while True:
        time.sleep(5)
        response = requests.get(f"{API_BASE}/v4/realtime/status", headers=HEADERS)
        status = response.json()

        if status["ready"]:
            print("Service is ready!")
            break
        print(f"Waiting... Status: {status['status']}")

# Step 4: Use the realtime service
websocket_url = status["endpoint"]
# Connect to websocket_url for realtime transcription

cURL​

# Step 1: Check status
curl -X GET https://api.scriptix.io/v4/realtime/status \
  -H "Authorization: Bearer YOUR_API_KEY"

# Step 2: Initialize (if needed)
curl -X POST https://api.scriptix.io/v4/realtime/initialize \
  -H "Authorization: Bearer YOUR_API_KEY"

# Step 3: Poll status
curl -X GET https://api.scriptix.io/v4/realtime/status \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript​

const API_BASE = "https://api.scriptix.io";
const headers = {
  "Authorization": "Bearer YOUR_API_KEY"
};

async function initializeRealtimeService() {
  // Step 1: Check status
  let response = await fetch(`${API_BASE}/v4/realtime/status`, { headers });
  let status = await response.json();

  // Step 2: Initialize if not ready
  if (!status.ready) {
    console.log("Service is not active. Initializing...");
    await fetch(`${API_BASE}/v4/realtime/initialize`, {
      method: "POST",
      headers
    });

    // Step 3: Poll until ready
    while (true) {
      await new Promise(resolve => setTimeout(resolve, 5000));
      response = await fetch(`${API_BASE}/v4/realtime/status`, { headers });
      status = await response.json();

      if (status.ready) {
        console.log("Service is ready!");
        break;
      }
      console.log(`Waiting... Status: ${status.status}`);
    }
  }

  // Step 4: Use the realtime service
  const websocketUrl = status.endpoint;
  return websocketUrl;
}

Important Notes​

  • Best Practice: Always check /status first before initializing to avoid unnecessary delays
  • Auto-scaling: The service automatically scales down after 30-60 minutes of inactivity
  • Initialization Time: Expect 1-5 minutes for the service to become ready
  • Polling Interval: Poll /status every 5-10 seconds during initialization
  • Organizations: Each organization should follow this workflow for efficient resource usage

Next Steps​

After the service is ready, you can: