> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Speech-to-Text
> Transcribe audio to text via WebSocket
Connect to the WebSocket and send STT requests to transcribe audio into text.
## Quick Start
1. Enter your API key in the authentication field
2. Click **Connect** to establish the WebSocket connection
3. Provide base64-encoded audio data
4. Click **Send** to receive transcription
## Request Message
After connecting, send a JSON message with the following structure:
Must be `"stt"`
Base64-encoded audio data.
Language code for transcription. Defaults to `"ar"` (Arabic).
Enable end-of-speech detection.
Threshold for end-of-speech detection (0.0 to 1.0).
The STT model to use for transcription. One of: `s2`, `s3`. Defaults to `s2`.
```json STT Request theme={null}
{
"type": "stt",
"payload": {
"audioBase64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=",
"language": "ar",
"isEosEnabled": true,
"eosThreshold": 0.3,
"model": "s2"
}
}
```
## Response Format
```text Transcription Result theme={null}
مرحبا بك في خدمة همسة
```
```json Error Response theme={null}
{
"type": "error",
"payload": {
"message": "Error generating transcription: Audio format not supported"
}
}
```
The transcribed text is returned as a **plain string**, not wrapped in JSON.
## Supported Audio Formats
Any audio format supported by the backend (WAV, MP3, etc.), base64-encoded.
## AsyncAPI
````yaml websocket/asyncapi-stt.json stt
id: stt
title: Speech-to-Text
description: Transcribe audio to text
servers:
- id: production
protocol: wss
host: api.tryhamsa.com/v1/realtime/ws
bindings: []
variables: []
address: /
parameters: []
bindings: []
operations:
- &ref_1
id: sendSTTRequest
title: Send STT Request
description: Send audio data to be transcribed to text
type: receive
messages:
- &ref_3
id: sttRequest
contentType: application/json
payload:
- name: STT Request
description: Request to transcribe audio to text
type: object
properties:
- name: type
type: string
description: Message type identifier
required: true
- name: payload
type: object
required: true
properties:
- name: audioBase64
type: string
description: Base64-encoded audio data.
required: true
- name: language
type: string
description: >-
Language code for transcription. Defaults to 'ar'
(Arabic).
required: false
- name: isEosEnabled
type: boolean
description: Enable end-of-speech detection.
required: false
- name: eosThreshold
type: number
description: Threshold for end-of-speech detection (0.0 to 1.0).
required: false
- name: model
type: string
description: The STT model to use for transcription. Defaults to 's2'.
enumValues:
- s2
- s3
required: false
headers: []
jsonPayloadSchema:
type: object
required:
- type
- payload
properties:
type:
type: string
const: stt
description: Message type identifier
x-parser-schema-id:
payload:
type: object
required:
- audioBase64
properties:
audioBase64:
type: string
description: Base64-encoded audio data.
x-parser-schema-id:
language:
type: string
default: ar
description: Language code for transcription. Defaults to 'ar' (Arabic).
x-parser-schema-id:
isEosEnabled:
type: boolean
default: true
description: Enable end-of-speech detection.
x-parser-schema-id:
eosThreshold:
type: number
default: 0.3
minimum: 0
maximum: 1
description: Threshold for end-of-speech detection (0.0 to 1.0).
x-parser-schema-id:
model:
type: string
enum:
- s2
- s3
default: s2
description: The STT model to use for transcription. Defaults to 's2'.
x-parser-schema-id:
x-parser-schema-id:
x-parser-schema-id: STTRequestPayload
title: STT Request
description: Request to transcribe audio to text
example: |-
{
"type": "stt",
"payload": {
"audioBase64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=",
"language": "ar",
"isEosEnabled": true,
"eosThreshold": 0.3,
"model": "s2"
}
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: sttRequest
bindings: []
extensions: &ref_0
- id: x-parser-unique-object-id
value: stt
- &ref_2
id: receiveSTTResponse
title: Receive STT Response
description: Receive the transcribed text or error
type: send
messages:
- &ref_4
id: sttResponse
contentType: text/plain
payload:
- type: string
description: Transcribed text result
x-parser-schema-id:
name: STT Response
headers: []
jsonPayloadSchema:
type: string
description: The transcribed text is sent as a plain string, not wrapped in JSON.
x-parser-schema-id:
title: STT Response
description: Transcribed text result
example: '"مرحبا بك في خدمة همسة"'
bindings: []
extensions:
- id: x-parser-unique-object-id
value: sttResponse
- &ref_5
id: errorResponse
contentType: application/json
payload:
- name: Error Response
description: Error message from the server
type: object
properties:
- name: type
type: string
description: error
required: false
- name: payload
type: object
required: false
properties:
- name: message
type: string
description: Error description
required: false
headers: []
jsonPayloadSchema:
type: object
properties:
type:
type: string
const: error
x-parser-schema-id:
payload:
type: object
properties:
message:
type: string
description: Error description
x-parser-schema-id:
x-parser-schema-id:
x-parser-schema-id: ErrorPayload
title: Error Response
description: Error message from the server
example: |-
{
"type": "error",
"payload": {
"message": "Invalid payload for message type: stt"
}
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: errorResponse
bindings: []
extensions: *ref_0
sendOperations:
- *ref_1
receiveOperations:
- *ref_2
sendMessages:
- *ref_3
receiveMessages:
- *ref_4
- *ref_5
extensions:
- id: x-parser-unique-object-id
value: stt
securitySchemes:
- id: apiKey
name: api_key
type: httpApiKey
description: API key passed as query parameter or X-Api-Key header
in: query
extensions: []
````