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

# Quickstart

> Convert text into lifelike speech

# Text to Speech Quickstart

Hamsa offers two TTS endpoints:

* **Jobs API** (`/v1/jobs/text-to-speech`) — Async job-based. Returns a job ID; audio is delivered via webhook or polling.
* **Realtime API** (`/v1/realtime/tts`) — Synchronous. Returns a WAV audio file directly.

## Prerequisites

* [Hamsa API Key](/overview/create-api-keys)

## Realtime TTS (synchronous)

Returns audio directly in the response.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.tryhamsa.com/v1/realtime/tts \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "text": "أهلاً و سهلاً بكم في همسة!",
      "speaker": "Amjad",
      "dialect": "pls",
      "expressiveness": 1
    }' \
    --output speech.wav
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.tryhamsa.com/v1/realtime/tts"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  data = {
      "text": "أهلاً و سهلاً بكم في همسة!",
      "speaker": "Amjad",
      "dialect": "pls",
      "expressiveness": 1
  }

  response = requests.post(url, headers=headers, json=data)

  with open("speech.wav", "wb") as f:
      f.write(response.content)
  ```
</CodeGroup>

## Jobs API (async)

Initiates a TTS job. The result is delivered via webhook or can be polled.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.tryhamsa.com/v1/jobs/text-to-speech \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "text": "أهلاً و سهلاً بكم في همسة!",
      "voiceId": "Amjad",
      "webhookUrl": "https://your-server.com/webhook"
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.tryhamsa.com/v1/jobs/text-to-speech"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  data = {
      "text": "أهلاً و سهلاً بكم في همسة!",
      "voiceId": "Amjad",
      "webhookUrl": "https://your-server.com/webhook"
  }

  response = requests.post(url, headers=headers, json=data)
  print(response.json())
  # Returns: { "success": true, "data": { "id": "...", "status": "PENDING", ... } }
  ```
</CodeGroup>

## Parameters

### Realtime API

| Parameter        | Type    | Required | Description                                                                                                                                    |
| ---------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `text`           | string  | Yes      | The text to convert to speech                                                                                                                  |
| `speaker`        | string  | Yes      | Voice name (e.g., "Amjad", "Layan") or UUID of a cloned voice                                                                                  |
| `dialect`        | string  | No       | Dialect code (e.g., `pls`, `egy`, `ksa`) — see [supported dialects](#supported-dialects)                                                       |
| `mulaw`          | boolean | No       | Use μ-law encoding for telephony (default: `false`)                                                                                            |
| `sampleRate`     | string  | No       | Output sample rate of the PCM audio: `8k` or `16k` (default: `16k`). PCM only — cannot be combined with `mulaw` (μ-law output is always 8 kHz) |
| `expressiveness` | number  | No       | How expressive the speech sounds, 0 (flat) to 2 (highly expressive) (default: `1`)                                                             |

### Jobs API

| Parameter     | Type   | Required | Description                                                                                           |
| ------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------- |
| `text`        | string | Yes      | The text to convert to speech                                                                         |
| `voiceId`     | string | Yes      | Voice ID to use. For cloned voices, [preload first](/api-reference/endpoint/preload-cloned-tts-voice) |
| `webhookUrl`  | string | No       | URL to receive the completed job result                                                               |
| `webhookAuth` | object | No       | Authentication for the webhook                                                                        |

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