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

01

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.

02

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.

03

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.

04

Speaker diarization

Multi-speaker audio comes back with speakers identified, so meetings and interviews read as a conversation rather than a wall of text.

05

Automatic punctuation

Transcripts arrive punctuated and formatted. There is no post-processing step between the API response and usable text.

06

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.

  1. 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>.

  2. 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.

  3. 03

    Choose a model

    Hamsa-General-V2.0 for media, podcasts and pre-recorded content; Hamsa-Conversational-V1.0 for meetings, calls and dialogue.

  4. 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.

  5. 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.

ItemDetail
Batch transcriptionA hosted media URL in, the transcript delivered by webhook or polling
Direct transcriptionBase64-encoded audio in, the text straight back in the response
StreamingOne persistent WebSocket connection serves both transcription and speech requests
ModelsHamsa-General-V2.0 for media; Hamsa-Conversational-V1.0 for calls and meetings
LanguagesArabic — all dialects, detected automatically — and English
SubtitlesSRT output with characters per line, lines per block, merge gap and duration controls
DeliveryWebhook with optional authentication on batch jobs; direct response on sync calls
AuthenticationA secret key in the Authorization header of every request, as Token <key>

Use cases

What teams build on the STT API

01

Subtitles and captions

SRT comes straight from the batch API with formatting you control, ready for video platforms and players without a conversion step.

02

Searchable media archives

Transcribe a back catalogue by URL, store the timestamped text, and let people search speech the way they search documents.

03

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.

04

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

Partner ecosystem

Trusted Across the
Technology Ecosystem

Hamsa works with leading technology companies, integrators, and solution providers to bring enterprise Voice AI to organizations across the region.