API Reference

Base URL#

http://localhost:8003/api/v1

All endpoints require the GROQ_API_KEY environment variable to be set for Whisper and LLM access.

Endpoints#

POST /api/v1/transcribe#

Transcribe an audio file. Accepts multipart form data with the audio file and optional query parameters.

Request: multipart/form-data

curl -X POST http://localhost:8003/api/v1/transcribe \
  -F "file=@recording.mp3" \
  -G -d "language=ar"

Response:

{
  "id": "tx-001",
  "text": "مرحبا، أريد الاستفسار عن خدمات الحكومة",
  "language": "ar",
  "duration": 4.5,
  "segments": [
    {"start": 0.0, "end": 2.1, "text": "مرحبا"},
    {"start": 2.1, "end": 4.5, "text": "أريد الاستفسار عن خدمات الحكومة"}
  ],
  "model": "whisper-large-v3",
  "created_at": "2024-01-15T10:30:00Z"
}

GET /api/v1/transcriptions#

List all transcriptions with pagination.

curl http://localhost:8003/api/v1/transcriptions?page=1&page_size=10

GET /api/v1/analytics#

Returns aggregated statistics across all transcriptions — total count, language distribution, average duration, and processing metrics.

curl http://localhost:8003/api/v1/analytics

POST /api/v1/voice/chat#

Send audio and receive a transcription plus an LLM-generated response in a single call. Supports multi-turn conversations via conversation_id.

Request: multipart/form-data

curl -X POST http://localhost:8003/api/v1/voice/chat \
  -F "file=@question.mp3" \
  -G -d "language=ar" \
  -G -d "conversation_id=conv-001"

Response:

{
  "transcription": "What services does the government offer?",
  "response": "The government offers a wide range of services...",
  "language": "en",
  "conversation_id": "conv-001",
  "duration": 3.2
}

WebSocket: /api/v1/transcribe/stream#

Real-time streaming transcription over WebSocket. Send raw audio bytes and receive JSON transcription results.

Connect:

const ws = new WebSocket("ws://localhost:8003/api/v1/transcribe/stream?token=JWT_TOKEN");

Send: Raw audio bytes (binary frames)

Receive: JSON messages

{"status": "processing"}

{
  "status": "completed",
  "text": "السلام عليكم",
  "language": "ar",
  "duration": 2.1,
  "segments": [
    {"start": 0.0, "end": 2.1, "text": "السلام عليكم"}
  ]
}

Environment Variables#

MCP Server#

Voice exposes a Model Context Protocol server at /mcp, enabling integration with AI assistants and development tools that support the MCP specification.