Skip to Content
Althea Studio

API Documentation

This API provides real-time voice transcription, voice tagging, and turn-yield prediction services over WebSocket. It is designed to handle audio streams, process them using various models, and return results such as transcriptions, voice tags, and turn-yield predictions.

Getting Started

To use this API, you need to establish a WebSocket connection and send audio data in real-time. The server processes the audio data and returns results based on the configured models and settings.

Prerequisites

  • A WebSocket client library (e.g., websockets for Python, ws for Node.js).
  • Valid API credentials.
caution

Currently the API is in alpha testing phase and credentials will be assigned per request basis.

For more information please contact support at support@althea.health

Initial Setup Packet

Upon connection, send an initial setup packet containing the session configuration and API credentials.

{
  "api_key": "your_api_key",
  "api_secret": "your_api_secret",
  "model": {
    "provider": "althea",
    "model_name": "General_large",
    "language": "en"
  },
  "audio_format": {
    "frame_rate": 16000,
    "sample_width": 2,
    "number_of_channels": 1
  },
  "setup": {
    "transcription": true,
    "tag": true,
    "intermediate": false,
    "turn_yield": true,
    "vad": true
  }
}

WebSocket Connection

Establishing a Connection

To establish a WebSocket connection, use the following URL format:

ws://<host>:<port>

Replace <host> and <port> with the values provided by the API service.

Sending Audio Data

After establishing the connection and sending the initial setup packet, you can start sending audio data in chunks. The audio data should be in the format specified in the initial setup packet.\

API Responses

Voice Activity Detection (VAD)

Detects voice activity in the audio stream.

Request

Send audio data in chunks.

Response

{
  "type": "vad",
  "timestamp": "2023-10-01T12:00:00Z",
  "status": "success",
  "data": [
    {
      "start": 0.0,
      "end": 1.0
    }
  ]
}

Voice Tagging

Tags the audio with voice labels.

Request

Send audio data in chunks.

Response

{
  "type": "voice_tag",
  "timestamp": "2023-10-01T12:00:00Z",
  "delay": 0.5,
  "status": "success",
  "data": {
    "voice_tag": "speech",
    "score": 0.95
  }
}

Transcription

Transcribes the audio data.

Request

Send audio data in chunks.

Response

{
  "type": "transcription",
  "timestamp": "2023-10-01T12:00:00Z",
  "delay": 1.0,
  "status": "success",
  "data": {
    "transcription": "Hello, how can I help you?"
  }
}

Turn-Yield Prediction

Predicts whether to yield the turn in a conversation.

Request

Send audio data in chunks.

Response

{
  "type": "turn_yield",
  "timestamp": "2023-10-01T12:00:00Z",
  "delay": 1.5,
  "status": "success",
  "data": {
    "turn_yield": true,
    "score": 0.85
  }
}

Error Handling

If an error occurs, the server will send an error message with details.

Example Error Response

{
  "error": "Invalid API credentials"
}

Example Usage

Python Client Example

import asyncio
import websockets
import json


async def main():
    uri = "ws://localhost:8000"
    async with websockets.connect(uri) as websocket:
        setup_packet = {
                "api_key": "your_api_key",
                "api_secret": "your_api_secret",
                "model": {
                    "provider": "althea",
                    "model_name": "General_large",
                    "language": "en"
                    },
                "audio_format": {
                    "frame_rate": 16000,
                    "sample_width": 2,
                    "number_of_channels": 1
                    },
                "setup": {
                    "transcription": True,
                    "tag": True,
                    "intermediate": False,
                    "turn_yield": True,
                    "vad": True
                    }
            }
        await websocket.send(json.dumps(setup_packet))


        while True:
            message = await websocket.recv()
            print(f"Received: {message}")




asyncio.run(main())

Node.js Client Example

const WebSocket = require('ws');


const ws = new WebSocket('ws://localhost:8000');


ws.on('open', function open() {
  const setupPacket = {
    api_key: 'your_api_key',
    api_secret: 'your_api_secret',
    model: {
      provider: 'althea',
      model_name: 'General_large',
      language: 'en',
    },
    audio_format: {
      frame_rate: 16000,
      sample_width: 2,
      number_of_channels: 1,
    },
    setup: {
      transcription: true,
      tag: true,
      intermediate: false,
      turn_yield: true,
      vad: true,
    },
  };
  ws.send(JSON.stringify(setupPacket));
});


ws.on('message', function incoming(data) {
  console.log(`Received: ${data}`);
});

This example demonstrates how to establish a WebSocket connection, send the initial setup packet, and receive responses from the server.

Conclusion

This API provides robust real-time voice processing capabilities, including transcription, voice tagging, and turn-yield prediction. By following the configuration and usage guidelines, you can integrate these features into your applications seamlessly. For any further questions or support, please refer to the official documentation or contact our support team.

previousModels introduction