Skip to content

Chapter 4 — APIs

Speech & Auth APIs

AMQP-based RPC interfaces for transcription and synthesis, their HTTP counterparts, and JWT authentication for the User Management platform.

Speech-to-Text integration

The transcription API is built on AMQP and uses RPC calls. This provides robust message queuing, load balancing under heavy traffic, and priority-based handling so that time-sensitive interactions are processed with minimal latency. The queue used for transcription is rpc_stt_queue , which connects the Speech-to-Text model with transcription request producers.

Request

  • messageId — unique identifier for the message.
  • conversationId — unique identifier for the conversation.
  • audioPath — path of the WAV audio (16 kHz) to transcribe.

Response

  • messageId — the identifier from the request.
  • body — the transcribed text.

HTTP endpoints

POST /api/document/create

Triggers format conversion where required, metadata extraction (sample rate, duration), segmentation and the creation of segments. Requires an Authorization bearer token. Parameters: audio (MultipartFile — MP3, WAV), sessionId (Long), dataset (TRAINING, VALIDATION or TEST) and optional tags . The response returns the id of the document created in the Conversation Monitor.

GET /api/document/{id}

Tracks the processing status of a created document by its ID.

GET /api/segment/document/{document_id}

Previews the transcription of a document per segment. Returns a JSON array of segment objects:

{
"id": <id of segment: long>,
"dateCreated": <creation date: datetime>,
"text": <transcription: string>,
"documentId": <document id: long>,
"orderId": <sequence number of the segment: int>,
"timeStart": <time_start>,
"timeEnd": <time_end>,
"path": <path to the audio segment>
}

Text-to-Speech integration

The synthesis API is also built on AMQP with RPC calls, providing load balancing under heavy traffic while keeping message queuing, data security and integrity straightforward. A request carries messageId , conversationId , gender (preferred voice gender) and text . The response is a waveform stream identified by the path of the synthesised WAV audio at 22.05 kHz.

POST /api/audio/synthesis

Request
{
"message": "Text to synthesize"
}

Response
Content-Type: audio/wav
<path to the generated audio file>

Authentication API

The User Management platform secures its endpoints with JWT. Users authenticate with their credentials to obtain a token, which must be included in the Authorization header of all protected requests.

  1. Login — the user sends credentials to the authentication endpoint.
  2. Token generation — the server validates the credentials and issues a JWT.
  3. Token usage — the client includes the token when accessing protected resources.
  4. Token verification — the server validates the token before processing the request.

POST https://<DOMAIN>:5082/api/user/login

Request
{
"username": "user@example.com",
"password": "password123"
}

Response
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}