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

# Models

> Learn about the models that power the Hamsa API

> Learn about the models that power the Hamsa API.

## Flagship models

### Text to Speech

<CardGroup cols={2} rows={1}>
  <Card title="Jobs API" href="#hamsa-tts-standard">
    Async TTS via `/v1/jobs/text-to-speech`

    <div>
      <div>
        Natural-sounding output optimized for Arabic dialects
      </div>

      <div>
        Multiple Arabic dialects + English
      </div>

      <div>
        Async job-based — result delivered via webhook
      </div>
    </div>
  </Card>

  <Card title="Realtime API" href="#hamsa-tts-realtime">
    Sync TTS via `/v1/realtime/tts`

    <div>
      <div>
        Low latency — returns WAV audio directly
      </div>

      <div>
        Arabic dialects + English
      </div>

      <div>
        Optimized for conversational AI and voice agents
      </div>
    </div>
  </Card>
</CardGroup>

### Speech to Text

<CardGroup cols={2} rows={1}>
  <Card title="Batch API" href="#hamsa-stt-batch-api">
    Async STT via `/v1/jobs/transcribe`

    <div>
      <div>
        High accuracy transcription for Arabic dialects
      </div>

      <div>
        Word-level timestamps
      </div>

      <div>
        Speaker diarization support
      </div>

      <div>
        Async job-based — result delivered via webhook
      </div>
    </div>
  </Card>

  <Card title="Realtime API" href="#hamsa-stt-realtime-api">
    Sync STT via `/v1/realtime/stt`

    <div>
      <div>
        Arabic dialects + English
      </div>

      <div>
        Base64-encoded audio input
      </div>

      <div>
        Returns transcription directly
      </div>

      <div>
        End-of-speech detection
      </div>
    </div>
  </Card>
</CardGroup>

## Models overview

The Hamsa API offers audio processing optimized for Arabic language, with support for multiple dialects and English.

| Endpoint                  | Description                                 | Languages                |
| ------------------------- | ------------------------------------------- | ------------------------ |
| `/v1/jobs/text-to-speech` | Async TTS — job-based with webhook delivery | Arabic dialects, English |
| `/v1/realtime/tts`        | Sync TTS — returns WAV audio directly       | Arabic dialects, English |
| `/v1/jobs/transcribe`     | Async STT — job-based with webhook delivery | Arabic, English          |
| `/v1/realtime/stt`        | Sync STT — returns transcription directly   | Arabic, English          |

## Hamsa TTS — Jobs API

The Jobs API (`/v1/jobs/text-to-speech`) is an async TTS endpoint. It creates a job and delivers the audio result via webhook. Best for batch processing and media content generation.

Use cases:

* **Content Creation**: Generate Arabic audio content, podcasts, and videos
* **Accessibility**: Audio versions of written Arabic content
* **E-Learning**: Educational content in Arabic with natural pronunciation
* **Media Production**: Professional-quality voiceovers

Parameters: `text`, `voiceId`, `webhookUrl`, `webhookAuth`

→ See the [TTS Quickstart](/text-to-speech/quickstart) for examples.

## Hamsa TTS — Realtime API

The Realtime API (`/v1/realtime/tts`) returns WAV audio directly in the response. Designed for real-time applications and voice agents.

Use cases:

* **Voice Agents**: Real-time voice agents and phone calls
* **Interactive Applications**: Chatbots requiring immediate voice response
* **Live Conversations**: Conversational AI applications

Parameters: `text`, `speaker`, `dialect`, `mulaw`, `sampleRate`, `expressiveness`

### Supported dialects

| Code    | Dialect                | Example voices |
| ------- | ---------------------- | -------------- |
| `pls`   | Palestinian            | Amjad, Layan   |
| `egy`   | Egyptian               | Mariam, Samir  |
| `syr`   | Syrian                 | Dalal, Mais    |
| `irq`   | Iraqi                  | Lyali, Fatma   |
| `jor`   | Jordanian              | Lana, Jasem    |
| `leb`   | Lebanese               | Carla, Majd    |
| `ksa`   | Saudi                  | Hiba, Fahd     |
| `uae`   | Emirati                | Salma, Dima    |
| `bah`   | Bahraini               | Mazen, Ruba    |
| `qat`   | Qatari                 | Deema, Faisal  |
| `kuw`   | Kuwaiti                | Mai, Hatem     |
| `oma`   | Omani                  | Aisha, Jaber   |
| `msa`   | Modern Standard Arabic | Salem, Tamim   |
| `ar-sa` | Arabic – Gulf          | Khalid, Rahma  |
| `en`    | English                | Emma, James    |

→ See the [TTS Quickstart](/text-to-speech/quickstart) for examples.

## Hamsa STT — Batch API

The Batch API (`/v1/jobs/transcribe`) is an async STT endpoint. Submit a media URL and receive the transcription via webhook or polling. Choose from two models:

| Model ID                    | Best for                                                |
| --------------------------- | ------------------------------------------------------- |
| `Hamsa-General-V2.0`        | General-purpose — media, podcasts, pre-recorded content |
| `Hamsa-Conversational-V1.0` | Conversational audio — meetings, calls, dialogues       |

Use cases:

* **Transcription Services**: Convert Arabic audio/video content to text
* **Meeting Documentation**: Capture and document Arabic conversations with speaker identification
* **Media Subtitling**: Generate SRT subtitles for Arabic media content
* **Content Analysis**: Process and index Arabic audio content

Key features:

* Word-level timestamps for each transcribed segment
* Speaker diarization for multi-speaker audio
* Automatic Arabic dialect detection (set `language` to `ar`)
* SRT subtitle export with configurable formatting
* Automatic punctuation and formatting

Parameters: `mediaUrl`, `model`, `language`, `webhookUrl`, `returnSrtFormat`, `srtOptions`

→ See the [STT Quickstart](/speech-to-text/quickstart) for examples.

## Hamsa STT — Realtime API

The Realtime API (`/v1/realtime/stt`) accepts base64-encoded audio and returns the transcription directly. For streaming, use the [WebSocket API](/websocket/websocket-api).

Use cases:

* **Voice Agents**: Real-time speech recognition for conversational AI
* **Live call transcription**: Transcribe Arabic calls in real time
* **Interactive applications**: Immediate transcription for chatbots and voice interfaces

Key features:

* Synchronous — returns transcription in the response
* End-of-speech detection with configurable threshold
* Arabic and English language support

Parameters: `audioBase64`, `language`, `isEosEnabled`, `eosThreshold`

→ See the [STT Quickstart](/speech-to-text/quickstart) for examples.

## Model selection guide

<AccordionGroup>
  <Accordion title="Requirements">
    <CardGroup cols={1}>
      <Card title="Batch / media content">
        Use the Jobs API (`/v1/jobs/text-to-speech`) for async processing with webhook delivery.
      </Card>

      <Card title="Real-time / voice agents">
        Use the Realtime API (`/v1/realtime/tts`) or WebSocket for low-latency streaming.
      </Card>

      <Card title="Arabic Dialects">
        Both TTS endpoints support 15 Arabic dialects + English. Choose based on latency requirements.
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="Use case">
    <CardGroup cols={1}>
      <Card title="Content creation">
        Use the Jobs API for professional Arabic content, media, and video narration.
      </Card>

      <Card title="Voice Agents">
        Use the Realtime API / WebSocket for real-time conversational applications.
      </Card>

      <Card title="Transcription">
        Use the Batch API (`/v1/jobs/transcribe`) with `Hamsa-General-V2.0` for media transcription or `Hamsa-Conversational-V1.0` for conversational audio.
      </Card>
    </CardGroup>
  </Accordion>
</AccordionGroup>

## Character limits

| Endpoint      | Character limit              |
| ------------- | ---------------------------- |
| WebSocket TTS | 2,000 characters per message |

<Note>
  For longer content, consider splitting the input into multiple requests.
</Note>

## Audio duration limits

| Endpoint                          | Audio duration limit | File size limit |
| --------------------------------- | -------------------- | --------------- |
| Batch API (`/v1/jobs/transcribe`) | 60 minutes           | 500 MB          |
| Realtime API (`/v1/realtime/stt`) | Per-request          | N/A             |
| WebSocket (`/v1/realtime/ws`)     | Streaming            | N/A             |

## Plans and Usage Limits

Your subscription plan determines your credit allocation, usage limits, and concurrent call capacity. See [Limits and Usage](/overview/limits-and-usage) for the full per-plan breakdown.

### API requests per minute vs concurrent requests

It's important to understand that **API requests per minute** and **concurrent requests** are different metrics that depend on your usage patterns.

API requests per minute can be different from concurrent requests since it depends on the length of time for each request and how the requests are batched.

**Example 1: Spaced requests**
If you had 60 requests per minute that each took 1 second to complete and you sent them each 1 second apart, the max concurrent requests would be 1 and the average would be 1.

**Example 2: Batched requests**
However, if you had 60 requests per minute that each took 3 seconds to complete but all fired at once, the max concurrent requests would be 60 and the average would be 3.

Since our system cares about concurrency, requests per minute matter less than how long each of the requests take and the pattern of when they are sent.