Hamsa API · Speech to Text
Arabic Speech to Text API
Three ways to call the same Arabic transcription models: an async jobs endpoint for recorded media, a synchronous endpoint for direct transcription, and a WebSocket for streaming. Set the language to Arabic and the dialect is detected for you.
- Batch, sync and streaming
- Dialects auto-detected
- Word-level timestamps
- Speaker diarization
- SRT subtitles with options
Capabilities
What the transcription API gives you back
Dialects without configuration
Set language to ar and the model detects Egyptian, Gulf, Levantine, Iraqi and other dialects on its own. English is the same API with language set to en.
Arabic mixed with English
Speech that switches between Arabic and English mid-sentence, common across the region, is transcribed as it was said rather than forced into one language.
Word-level timestamps
Every segment carries its words with start and end times, precise enough to highlight the current word during playback or cut audio to the transcript.
Speaker diarization
Multi-speaker audio comes back with speakers identified, so meetings and interviews read as a conversation rather than a wall of text.
Automatic punctuation
Transcripts arrive punctuated and formatted. There is no post-processing step between the API response and usable text.
Subtitles you can tune
Ask for SRT with returnSrtFormat and shape it with options: characters per line, lines per block, one speaker per subtitle, merge gap and minimum duration.
Integration
From API key to transcript
The whole path, in the order you will write it.
- 01
Create a secret key
Create a secret key in the dashboard and keep it on your server. Every request carries it in the Authorization header as Token <key>.
- 02
Pick the endpoint for your audio
Recorded files go to the batch jobs endpoint as a media URL. Short audio goes to the synchronous endpoint as base64. Live audio streams over the WebSocket.
- 03
Choose a model
Hamsa-General-V2.0 for media, podcasts and pre-recorded content; Hamsa-Conversational-V1.0 for meetings, calls and dialogue.
- 04
Send the audio
The batch endpoint takes mediaUrl, model and language, plus an optional title and SRT options. The sync endpoint takes the audio itself, base64-encoded.
- 05
Receive the transcript
Batch jobs deliver to your webhookUrl, with optional webhook authentication, or you poll the job. The sync endpoint returns the text in the response.
Reference
The Speech to Text API at a glance
Each row links to its page in the API docs — the authoritative reference, with full schemas and runnable code samples.
| Item | Detail |
|---|---|
| Batch transcription | A hosted media URL in, the transcript delivered by webhook or polling |
| Direct transcription | Base64-encoded audio in, the text straight back in the response |
| Streaming | One persistent WebSocket connection serves both transcription and speech requests |
| Models | Hamsa-General-V2.0 for media; Hamsa-Conversational-V1.0 for calls and meetings |
| Languages | Arabic — all dialects, detected automatically — and English |
| Subtitles | SRT output with characters per line, lines per block, merge gap and duration controls |
| Delivery | Webhook with optional authentication on batch jobs; direct response on sync calls |
| Authentication | A secret key in the Authorization header of every request, as Token <key> |
Use cases
What teams build on the STT API
Subtitles and captions
SRT comes straight from the batch API with formatting you control, ready for video platforms and players without a conversion step.
Searchable media archives
Transcribe a back catalogue by URL, store the timestamped text, and let people search speech the way they search documents.
Meeting and call records
The conversational model plus diarization turns recorded meetings into minutes that say who said what, with timestamps to jump back to the audio.
Live voice features
The WebSocket stream feeds live transcription into call monitoring, captioning and voice-driven interfaces as people speak.
FAQ
Questions about the Speech to Text API
Which endpoint should I use?
+
Use the batch endpoint for recorded files you can host at a URL: it runs async and delivers by webhook. Use the sync endpoint when you have the audio in hand and want the text in the response. Use the WebSocket when audio arrives as a stream.
Do I have to specify the Arabic dialect?
+
No. Set language to ar and the model detects the dialect automatically — Egyptian, Gulf, Levantine, Iraqi and others — and transcribes accordingly. There is no per-dialect configuration.
How do I get the result of a batch job?
+
Pass a webhookUrl when you create the job and the completed transcription is posted there; webhookAuth secures the callback. You can also poll the job by its ID.
Can it handle Arabic and English in the same recording?
+
Yes. The models are built for code-switched speech, so sentences that move between Arabic and English are transcribed as spoken.
Can the API return subtitles directly?
+
Yes. Set returnSrtFormat to true on a batch job and tune the output with srtOptions: maximum characters per line, lines per subtitle, one speaker per subtitle, the gap below which segments merge, and the minimum duration a subtitle stays on screen.
Keep reading
Hamsa API · Text to Speech
Arabic Text to Speech API
Synchronous, async and streaming Arabic speech generation in 14 dialects plus English, with telephony output and cloned voices.
Read →Hamsa Media · API
Media Platform API
Transcription, text-to-speech and AI content as async jobs over REST, with webhook delivery and full job management.
Read →Hamsa Agents · API
AI Phone Agents API
Create agents, connect numbers, start calls, run campaigns and read every conversation over REST, with webhooks for live call events.
Read →


