# Authentication
Source: https://docs.faseeh.ai/api-reference/authentication



## API Keys

To access the Faseeh API, you'll need an API key. This key serves as your authentication credential and is required for all API requests.

### How it works

Include your API key in every request by adding it to the `x-api-key` HTTP header:

```bash theme={null}
x-api-key: YOUR_API_KEY
```

### API Key Features

Your API keys can be configured with:

* **Endpoint restrictions:** Control which API endpoints each key can access
* **Usage limits:** Set custom quotas to manage and monitor your API consumption

### Security Best Practices

<Warning>
  Keep your API key secure and private. Never commit it to version control, share it publicly, or include it in client-side applications where it could be exposed.
</Warning>

### Making requests

You can paste the command below into your terminal to run your first API request. Make sure to replace `$FASEEH_API_KEY` with your secret API key.

```bash theme={null}
curl 'https://api.faseeh.ai/api/v1/text-to-speech/faseeh-v1-preview' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: $FASEEH_API_KEY' \
  -d '{
    "voice_id": "ar-najdi-male-2",
    "text": "مرحبا بك في فصيح",
    "stability": 0.5,
    "streaming": true,
    "speed": 1
  }'
```

Example with Python:

```python theme={null}
import requests

headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

response = requests.post(
    'https://api.faseeh.ai/api/v1/text-to-speech/faseeh-v1-preview',
    headers=headers,
    json={
        'voice_id': 'ar-najdi-male-2',
        'text': 'مرحبا بك في فصيح',
        'stability': 0.5,
        'streaming': True,
        'speed': 1
    }
)
```

Example with Node.js:

```javascript theme={null}
const response = await fetch('https://api.faseeh.ai/api/v1/text-to-speech/faseeh-v1-preview', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    voice_id: 'ar-najdi-male-2',
    text: 'مرحبا بك في فصيح',
    stability: 0.5,
    streaming: true,
    speed: 1
  })
});
```


# Denoise
Source: https://docs.faseeh.ai/api-reference/denoise

POST /denoise
Remove background noise and isolate voice from audio files. Upload an audio file and receive a cleaned audio file with enhanced voice clarity.

## Authentication

Requires API key authentication via `x-api-key` header.

## Request

**Content-Type:** `multipart/form-data`

### Form Data

| Field   | Type | Required | Description                                                 |
| ------- | ---- | -------- | ----------------------------------------------------------- |
| `audio` | File | Yes      | Audio file to denoise (max 200 MB, max 15 minutes duration) |

### File Limits

* **Maximum file size:** 200 MB
* **Maximum duration:** 15 minutes

Supported audio formats: WAV, MP3, M4A, FLAC, OGG

## Response

**Status Code:** `200 OK`

**Headers:**

* `Content-Type: audio/wav`
* `Cache-Control: no-cache`
* `Content-Length: <file_size>`

**Body:** Denoised audio file (WAV format)

### Error Responses

**400 Bad Request**

```json theme={null}
{
  "errorCode": "400xx",
  "errorMessage": "File size exceeds 200 MB limit"
}
```

```json theme={null}
{
  "errorCode": "400xx",
  "errorMessage": "Audio duration exceeds 15 minutes limit"
}
```

**401 Unauthorized**

```json theme={null}
{
  "errorCode": "40101",
  "errorMessage": "Invalid or missing API key"
}
```

**402 Payment Required**

```json theme={null}
{
  "errorCode": "40201",
  "errorMessage": "Insufficient wallet balance"
}
```

## Example Usage

### JavaScript

```javascript theme={null}
const formData = new FormData();
const audioFile = document.querySelector('input[type="file"]').files[0];
formData.append("audio", audioFile);

const response = await fetch('https://api.faseeh.ai/api/v1/denoise', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    // Note: Content-Type is set automatically by FormData
  },
  body: formData,
});

if (response.ok) {
  const audioBlob = await response.blob();
  const audioUrl = URL.createObjectURL(audioBlob);
  // Use audioUrl to play or download the denoised audio
} else {
  const error = await response.json();
  console.error('Error:', error);
}
```

### Python

```python theme={null}
import requests

url = "https://api.faseeh.ai/api/v1/denoise"
headers = {
    "x-api-key": "YOUR_API_KEY"
}

with open("input_audio.wav", "rb") as audio_file:
    files = {"audio": audio_file}
    response = requests.post(url, files=files, headers=headers)

if response.status_code == 200:
    with open("denoised_audio.wav", "wb") as f:
        f.write(response.content)
    print("Denoised audio saved successfully")
else:
    print(f"Error: {response.status_code} - {response.text}")
```

### cURL

```bash theme={null}
curl -X POST "https://api.faseeh.ai/api/v1/denoise" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "audio=@input_audio.wav" \
  --output denoised_audio.wav
```

<Note>
  **File Limits**: Ensure your audio file is under 200 MB and 15 minutes duration. Larger files will be rejected with a 400 error.
</Note>


# Endpoints
Source: https://docs.faseeh.ai/api-reference/endpoints



This guide provides instructions for configuring your applications to use Faseeh's API endpoint.

## Main API Endpoint

Faseeh's API base URL:

```
https://api.faseeh.ai/api/v1
```

### How to Use

1. **Use the base URL**: All API requests should use `https://api.faseeh.ai/api/v1` as the base URL
2. **Include your API key**: Add your API key in the `x-api-key` header for authentication
3. **Set Content-Type**: Include `Content-Type: application/json` header for JSON requests

## Direct API Calls

### cURL Example

```bash theme={null}
# Base URL: https://api.faseeh.ai/api/v1

curl -X POST "https://api.faseeh.ai/api/v1/text-to-speech/faseeh-v1-preview" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_id": "ar-najdi-male-2",
    "text": "مرحبا بك في فصيح",
    "stability": 0.5,
    "streaming": true,
    "speed": 1
  }'
```


# Errors
Source: https://docs.faseeh.ai/api-reference/errors



The Faseeh API uses standard HTTP status codes and custom error codes to indicate the type of error that occurred. All errors are returned in a consistent JSON format.

## Error Response Format

All error responses follow this structure:

```json theme={null}
{
  "errorCode": 40001,
  "errorMessage": "Error description"
}
```

The HTTP status code in the response header corresponds to the error type, while `errorCode` provides a specific numeric code for programmatic error handling.

## Error Types

### AuthenticationError

Occurs when authentication fails or API key is invalid.

**Status Code**: `401` (Unauthorized)

**Error Codes**: `40101`

**Common Scenarios**:

* Missing `x-api-key` header
* Invalid API key format
* Expired API key
* Revoked or deleted API key
* Invalid JWT signature

**Properties**:

* `errorCode` (number): Error code `40101`
* `errorMessage` (string): Human-readable error message

**Example**:

```json theme={null}
{
  "errorCode": 40101,
  "errorMessage": "Invalid API key"
}
```

***

### ValidationError

Occurs when request validation fails due to invalid or missing parameters.

**Status Code**: `400` (Bad Request)

**Error Code**: `40001`

**Common Scenarios**:

* Empty or missing required fields
* Text too short (less than 3 words or 10 characters)
* Invalid parameter values (out of range)
* Invalid message types (WebSocket)
* Missing voice embeddings
* Payload too large

**Properties**:

* `errorCode` (number): Error code `40001`
* `errorMessage` (string): Human-readable error message describing the validation issue

**Example**:

```json theme={null}
{
  "errorCode": 40001,
  "errorMessage": "Text must have at least 3 words and 10 characters"
}
```

***

### InsufficientBalanceError

Occurs when the user's account balance is insufficient to complete the request.

**Status Code**: `402` (Payment Required)

**Error Code**: `40201`

**Properties**:

* `errorCode` (number): Error code `40201`
* `errorMessage` (string): Error message describing the insufficient balance with required and available amounts

**Example**:

```json theme={null}
{
  "errorCode": 40201,
  "errorMessage": "Insufficient wallet balance. Required: $0.50, Available: $0.25"
}
```

**Note**: The error message includes the exact amount required and the current available balance. Users should recharge their account to continue using the API.

***

### ModelAccessError

Occurs when the user attempts to access a model they don't have permission to use.

**Status Code**: `403` (Forbidden)

**Error Code**: `40301`

**Properties**:

* `errorCode` (number): Error code `40301`
* `errorMessage` (string): Error message describing the access restriction

**Example**:

```json theme={null}
{
  "errorCode": 40301,
  "errorMessage": "This model is not enabled for your account. Please contact support@faseeh.ai to get access."
}
```

**Note**: Some models require special access. Contact support to request access to restricted models.

***

### ConcurrencyLimitError

Occurs when the user has exceeded their concurrent request limit based on their subscription plan.

**Status Code**: `429` (Too Many Requests)

**Error Code**: `42901`

**Properties**:

* `errorCode` (number): Error code `42901`
* `errorMessage` (string): Error message describing the concurrency limit with current and maximum values

**Example**:

```json theme={null}
{
  "errorCode": 42901,
  "errorMessage": "Concurrency limit exceeded. Maximum 5 concurrent requests allowed. Current: 6. Please upgrade your plan https://app.faseeh.ai/en/subscription or contact support@faseeh.ai for more information."
}
```

**Concurrency Limits by Plan**:

* **Basic Plan**: 2 concurrent requests
* **Starter Plan**: 5 concurrent requests
* **Growth Plan**: 10 concurrent requests
* **Scale Plan**: 20 concurrent requests
* **Free/No Plan**: 1 concurrent request

**Note**: Wait for current requests to complete, or upgrade your plan to increase your concurrency limit.

***

### InternalError

Occurs when an internal server error happens or external services fail.

**Status Code**: `500` (Internal Server Error), `502` (Bad Gateway), `503` (Service Unavailable), `504` (Gateway Timeout)

**Error Code**: `50001`

**Common Scenarios**:

* Internal server errors
* External API failures (ElevenLabs)
* Database connection issues
* File storage failures (R2)
* Request timeouts
* Connection errors

**Properties**:

* `errorCode` (number): Error code `50001`
* `errorMessage` (string): Error message describing the issue

**Example**:

```json theme={null}
{
  "errorCode": 50001,
  "errorMessage": "Internal server error"
}
```

***

### NotFoundError

Occurs when a requested resource doesn't exist.

**Status Code**: `404` (Not Found)

**Error Code**: `40401` (or `50001` for some cases)

**Common Scenarios**:

* Model not found
* Voice not found
* Resource endpoint not found

**Properties**:

* `errorCode` (number): Error code (typically `40401` or `50001`)
* `errorMessage` (string): Error message describing what wasn't found

**Example**:

```json theme={null}
{
  "errorCode": 40401,
  "errorMessage": "Model not found: faseeh-v2-preview"
}
```

***

## Error Code Reference

| Error Code | HTTP Status     | Error Type               | Description                               |
| ---------- | --------------- | ------------------------ | ----------------------------------------- |
| `40001`    | 400             | ValidationError          | Request validation failed                 |
| `40101`    | 401             | AuthenticationError      | Authentication failed or invalid API key  |
| `40201`    | 402             | InsufficientBalanceError | Insufficient account balance              |
| `40301`    | 403             | ModelAccessError         | Model access denied                       |
| `40401`    | 404             | NotFoundError            | Resource not found                        |
| `42901`    | 429             | ConcurrencyLimitError    | Concurrent request limit exceeded         |
| `50001`    | 500/502/503/504 | InternalError            | Internal server or external service error |

***

## Handling Errors

When an error occurs, check the HTTP status code in the response header and the `errorCode` field in the response body to determine the appropriate action:

### 400 - ValidationError

* **Action**: Review the request parameters and fix validation issues
* **Common fixes**:
  * Ensure all required fields are provided
  * Check text length meets minimum requirements (3 words, 10 characters)
  * Verify parameter values are within valid ranges
  * Reduce payload size if exceeding limits

### 401 - AuthenticationError

* **Action**: Verify your API key is correct and valid
* **Common fixes**:
  * Ensure `x-api-key` header is included in the request
  * Check that the API key hasn't expired
  * Verify the API key format is correct
  * Generate a new API key if the current one was revoked

### 402 - InsufficientBalanceError

* **Action**: Recharge your account balance
* **Common fixes**:
  * Check your current balance
  * Add funds to your account via the dashboard
  * Enable auto-topup to automatically recharge when balance is low
  * Verify the cost of the operation before making the request

### 403 - ModelAccessError

* **Action**: Request access to the model
* **Common fixes**:
  * Contact [support@faseeh.ai](mailto:support@faseeh.ai) to request access
  * Verify your subscription plan includes access to the model
  * Check if the model ID is correct

### 404 - NotFoundError

* **Action**: Verify the resource exists
* **Common fixes**:
  * Check that the model ID, voice ID, or resource ID is correct
  * Verify the resource hasn't been deleted
  * Ensure you're using the correct endpoint

### 429 - ConcurrencyLimitError

* **Action**: Reduce concurrent requests or upgrade your plan
* **Common fixes**:
  * Wait for current requests to complete
  * Reduce the number of simultaneous API calls
  * Upgrade your subscription plan to increase concurrency limits
  * Implement request queuing in your application

### 500/502/503/504 - InternalError

* **Action**: Retry the request or contact support
* **Common fixes**:
  * Retry the request after a short delay (exponential backoff recommended)
  * Check the error message for specific details
  * If the issue persists, contact [support@faseeh.ai](mailto:support@faseeh.ai) with:
    * The error code and message
    * The request that caused the error
    * Timestamp of the error
  * For external API errors, wait a few minutes and retry

***

## Best Practices

1. **Implement Retry Logic**: For 500-level errors, implement exponential backoff retry logic
2. **Handle Rate Limits**: Monitor for 429 errors and implement request queuing
3. **Validate Inputs**: Prevent 400 errors by validating inputs before sending requests
4. **Monitor Balance**: Check balance before making requests to avoid 402 errors
5. **Cache API Keys**: Store API keys securely and handle expiration gracefully
6. **Error Logging**: Log all errors with context for debugging
7. **User-Friendly Messages**: Display user-friendly error messages based on error codes

***

## WebSocket Errors

For WebSocket connections, errors are sent as JSON messages:

```json theme={null}
{
  "type": "error",
  "message": "Error description"
}
```

Common WebSocket errors:

* Missing authentication: `"x-api-key or Authorization header is required. Provide it in query string, headers, or initConnection message."`
* Invalid message type: `'Invalid message type. Expected "voice-request"'`

***

## Support

If you encounter errors that aren't covered in this documentation or need assistance:

* **Email**: [support@faseeh.ai](mailto:support@faseeh.ai)
* **Documentation**: [https://docs.faseeh.ai](https://docs.faseeh.ai)
* **Status Page**: Check our status page for service updates


# Get Models
Source: https://docs.faseeh.ai/api-reference/models

GET /models
Retrieve a list of all available voice synthesis models

Retrieve a list of all available voice synthesis models.

## Authentication

Requires API key authentication via `x-api-key` header.

## Response

Returns an array of model objects.

### Response Schema

Each model object contains:

| Field         | Type           | Description                        |
| ------------- | -------------- | ---------------------------------- |
| `id`          | string (UUID)  | Unique identifier for the model    |
| `model_id`    | string         | Model identifier used in API calls |
| `model_name`  | string         | Human-readable model name          |
| `description` | string \| null | Detailed description of the model  |

### Example Request

```bash theme={null}
curl -X GET "https://api.faseeh.ai/api/v1/models" \
  -H "x-api-key: YOUR_API_KEY"
```

### Example Response

```json theme={null}
[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "model_id": "faseeh-arabic-v1",
    "model_name": "Faseeh Arabic v1",
    "description": "High-quality Arabic voice synthesis supporting multiple dialects"
  },
  {
    "id": "123e4567-e89b-12d3-a456-426614174001",
    "model_id": "faseeh-arabic-fast",
    "model_name": "Faseeh Arabic Fast",
    "description": "Fast Arabic voice synthesis with lower latency"
  }
]
```

## Usage

Use the `model_id` from the response in text-to-speech generation endpoints:

* `POST /text-to-speech/:model_id` - HTTP endpoint
* `WS /text-to-speech` - WebSocket endpoint (include `model_id` in initConnection message)

<Note>
  **Caching**: Model information doesn't change frequently. Consider caching the model list to reduce API calls.
</Note>


# Quickstart
Source: https://docs.faseeh.ai/api-reference/quickstart



## Introduction

Faseeh provides a RESTful API that enables you to integrate Arabic text-to-speech capabilities into your applications. You can interact with the API through standard HTTP requests from any programming language or framework.

The API supports:

* High-quality Arabic voice synthesis
* Multiple Arabic dialects (Najdi, Hijazi, Emirati, and more)
* Streaming audio output
* Real-time text-to-speech conversion
* Customizable voice parameters (stability, speed)

## Getting Started

To get started with the Faseeh API:

1. **Get your API key**: Sign up at [app.faseeh.ai](https://app.faseeh.ai) and generate an API key
2. **Make your first request**: Use the API endpoint with your API key in the `x-api-key` header
3. **Explore the documentation**: Check out the [Authentication](/api-reference/authentication) and [Endpoints](/api-reference/endpoints) guides

## Quick Resources

<CardGroup>
  <Card title="Get API Key" icon="key" href="https://app.faseeh.ai/en/home">
    Generate and manage your API keys from the dashboard
  </Card>

  <Card title="Text To Speech API" icon="microphone" href="/api-reference/text-to-speech-stream">
    Learn how to use the Text-to-Speech API endpoints
  </Card>
</CardGroup>


# API Rate Limits
Source: https://docs.faseeh.ai/api-reference/rate-limits



The Faseeh API uses a credit-based system with concurrent request limits to ensure fair usage and optimal performance for all users.

## Concurrent Requests

For streaming text-to-speech requests, Faseeh enforces concurrent request limits based on your subscription plan. This ensures stable performance and prevents system overload.

**Concurrent Request Limits by Plan**:

* **Basic**: 2 concurrent requests
* **Starter**: 5 concurrent requests
* **Growth**: 10 concurrent requests
* **Scale**: 20 concurrent requests
* **Enterprise**: Unlimited concurrent requests

<Note>
  When you exceed your concurrent request limit, you'll receive a `42901` error (ConcurrencyLimitError). You can either wait for existing requests to complete or upgrade your plan to increase your limit.
</Note>

## Best Practices

1. **Monitor your usage**: Check your credit balance and concurrent request limits regularly
2. **Plan ahead**: Consider your usage patterns when selecting a subscription plan
3. **Handle rate limits**: Implement retry logic with exponential backoff for 429 errors

## Subscription Plans

For detailed information about subscription plans, credit limits, concurrent request limits, and pricing, visit:

**[View Subscription Plans →](https://app.faseeh.ai/en/subscription)**


# Text-to-Speech
Source: https://docs.faseeh.ai/api-reference/text-to-speech-post

POST /text-to-speech/{model_id}
Generate speech from Arabic text using a specific model. Supports both streaming and non-streaming responses.

Generate speech from Arabic text and receive a complete WAV audio file. The entire audio is generated before being returned, ensuring complete audio quality.

## Authentication

Requires API key authentication via `x-api-key` header.

## Path Parameters

| Parameter  | Type   | Required | Description                                |
| ---------- | ------ | -------- | ------------------------------------------ |
| `model_id` | string | Yes      | The model identifier to use for generation |

## Request Body

| Field       | Type    | Required | Description                                                                                      |
| ----------- | ------- | -------- | ------------------------------------------------------------------------------------------------ |
| `voice_id`  | string  | Yes      | The voice ID to use for synthesis                                                                |
| `text`      | string  | Yes      | The Arabic text to convert to speech                                                             |
| `stability` | number  | Yes      | Voice stability (0.0 to 1.0). Higher values produce more consistent output                       |
| `speed`     | number  | No       | Speech speed (0.7 to 1.2, default 1.0). Values below 1.0 slow down speech, above 1.0 speed it up |
| `streaming` | boolean | Yes      | Must be `false` for complete WAV file response                                                   |

### Example Request Body

```json theme={null}
{
  "voice_id": "voice_123",
  "text": "مرحبا بك في فصيح كيف يمكنني مساعدتك اليوم",
  "stability": 0.5,
  "speed": 1.0,
  "streaming": false
}
```

## Response

**Status Code:** `200 OK`

**Headers:**

* `Content-Type: audio/wav`
* `Cache-Control: no-cache`
* `Content-Length: <file_size>`

**Body:** Complete WAV audio file

### Error Responses

**400 Bad Request**

```json theme={null}
{
  "errorCode": "400xx",
  "errorMessage": "Model not found: invalid_model_id"
}
```

**402 Payment Required**

```json theme={null}
{
  "errorCode": "402xx",
  "errorMessage": "Insufficient wallet balance. Required: $0.05, Available: $0.02"
}
```

## Example Usage

### JavaScript

```javascript theme={null}
const response = await fetch('https://api.faseeh.ai/api/v1/text-to-speech/MODEL_ID', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    voice_id: 'VOICE_ID',
    text: 'مرحبا بك في فصيح كيف يمكنني مساعدتك اليوم',
    stability: 0.5,
    speed: 1.0,
    streaming: false,
  }),
});

const audioBlob = await response.blob();
const audioUrl = URL.createObjectURL(audioBlob);
// Use audioUrl to play or download the audio
```

### Python

```python theme={null}
import requests

url = "https://api.faseeh.ai/api/v1/text-to-speech/MODEL_ID"
headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "voice_id": "VOICE_ID",
    "text": "مرحبا بك في فصيح كيف يمكنني مساعدتك اليوم",
    "stability": 0.5,
    "speed": 1.0,
    "streaming": False
}

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

if response.status_code == 200:
    with open("output.wav", "wb") as f:
        f.write(response.content)
else:
    print(f"Error: {response.status_code} - {response.text}")
```

## Cost Calculation

The cost is calculated based on:

* Text length (number of characters)
* Model cost per character

Cost is deducted from your wallet balance upon successful generation.

<Note>
  **Wallet Balance**: Ensure your wallet has sufficient balance before making requests. Check your balance in the [Faseeh dashboard](https://app.faseeh.ai/en/api-keys).
</Note>


# Text-to-Speech Stream
Source: https://docs.faseeh.ai/api-reference/text-to-speech-stream

POST /text-to-speech/{model_id}
Generate speech from Arabic text using a specific model. Supports both streaming and non-streaming responses.

Generate speech from Arabic text with streaming PCM16 audio output. Audio chunks are streamed as they're generated, providing low-latency audio delivery.

## Authentication

Requires API key authentication via `x-api-key` header.

## Path Parameters

| Parameter  | Type   | Required | Description                                |
| ---------- | ------ | -------- | ------------------------------------------ |
| `model_id` | string | Yes      | The model identifier to use for generation |

## Request Body

| Field       | Type    | Required | Description                                                                                      |
| ----------- | ------- | -------- | ------------------------------------------------------------------------------------------------ |
| `voice_id`  | string  | Yes      | The voice ID to use for synthesis                                                                |
| `text`      | string  | Yes      | The Arabic text to convert to speech                                                             |
| `stability` | number  | Yes      | Voice stability (0.0 to 1.0). Higher values produce more consistent output                       |
| `speed`     | number  | No       | Speech speed (0.7 to 1.2, default 1.0). Values below 1.0 slow down speech, above 1.0 speed it up |
| `streaming` | boolean | Yes      | Must be `true` for streaming response                                                            |

### Example Request Body

```json theme={null}
{
  "voice_id": "voice_123",
  "text": "مرحبا بك في فصيح كيف يمكنني مساعدتك اليوم",
  "stability": 0.5,
  "speed": 1.0,
  "streaming": true
}
```

## Response

**Status Code:** `200 OK`

**Headers:**

* `Content-Type: audio/raw;codec=pcm16;rate=24000;channels=1`
* `Cache-Control: no-cache`
* `Connection: keep-alive`

**Body:** Stream of PCM16 audio chunks (24kHz, mono)

### Error Responses

**400 Bad Request**

```json theme={null}
{
  "errorCode": "400xx",
  "errorMessage": "Model not found: invalid_model_id"
}
```

**402 Payment Required**

```json theme={null}
{
  "errorCode": "402xx",
  "errorMessage": "Insufficient wallet balance. Required: $0.05, Available: $0.02"
}
```

## Example Usage

### JavaScript

```javascript theme={null}
const response = await fetch('https://api.faseeh.ai/api/v1/text-to-speech/MODEL_ID', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    voice_id: 'VOICE_ID',
    text: 'مرحبا بك في فصيح كيف يمكنني مساعدتك اليوم',
    stability: 0.5,
    speed: 1.0,
    streaming: true,
  }),
});

const reader = response.body.getReader();
const chunks = [];

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  chunks.push(value);
}

// Combine chunks into single audio buffer
const audioBuffer = new Uint8Array(chunks.reduce((acc, chunk) => acc + chunk.length, 0));
let offset = 0;
for (const chunk of chunks) {
  audioBuffer.set(chunk, offset);
  offset += chunk.length;
}
```

### Python

```python theme={null}
import requests

url = "https://api.faseeh.ai/api/v1/text-to-speech/MODEL_ID"
headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "voice_id": "VOICE_ID",
    "text": "مرحبا بك في فصيح كيف يمكنني مساعدتك اليوم",
    "stability": 0.5,
    "speed": 1.0,
    "streaming": True
}

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

if response.status_code == 200:
    with open("output.pcm", "wb") as f:
        for chunk in response.iter_content(chunk_size=8192):
            if chunk:
                f.write(chunk)
else:
    print(f"Error: {response.status_code} - {response.text}")
```

## Cost Calculation

The cost is calculated based on:

* Text length (number of characters)
* Model cost per character

Cost is deducted from your wallet balance upon successful generation.

<Note>
  **Wallet Balance**: Ensure your wallet has sufficient balance before making requests. Check your balance in the [Faseeh dashboard](https://app.faseeh.ai/en/api-keys).
</Note>


# Voice Clone
Source: https://docs.faseeh.ai/api-reference/voice-clone

POST /voices/clone
Create a cloned voice from an audio file. This endpoint allows you to create a new voice by providing a voice sample and reference audio.

<Note>
  **Important**: Before using this endpoint, you must first generate a voice preview using the [Voice Preview API](/api-reference/voice-preview). Use the preview audio file as `voice_file` and the original audio file as `reference_audio_file` when cloning the voice.
</Note>

## Authentication

Requires API key authentication via `x-api-key` header.

## Request

**Content-Type:** `multipart/form-data` (set automatically when using FormData/files)

### Form Data

| Field                  | Type   | Required | Description                                                                |
| ---------------------- | ------ | -------- | -------------------------------------------------------------------------- |
| `voice_file`           | File   | Yes      | The generated preview audio file from the preview API                      |
| `reference_audio_file` | File   | Yes      | The original audio file used for the preview                               |
| `text`                 | string | Yes      | The text used in preview generation                                        |
| `stability`            | number | Yes      | Voice stability (0.0 to 1.0). Higher values produce more consistent output |
| `name`                 | string | Yes      | Name for the cloned voice                                                  |
| `model`                | string | Yes      | Model identifier to use for voice cloning                                  |
| `description`          | string | No       | Description of the voice                                                   |
| `gender`               | string | No       | Gender of the voice (e.g., "male", "female")                               |
| `age`                  | string | No       | Age category of the voice (e.g., "middle", "elderly")                      |
| `languages`            | string | No       | Comma-separated list of language codes (e.g., "ar,en")                     |
| `dialects`             | string | No       | Comma-separated list of dialects (e.g., "najdi,hijazi")                    |
| `avatar_url`           | string | No       | URL to an avatar image for the voice (you can put your image URL here)     |

### Notes

* `voice_file` should be the audio file generated from the voice preview API
* `reference_audio_file` should be the original audio file you used when generating the preview
* `text` should match the text you used when generating the preview
* The voice will be assigned a unique `voice_id` automatically upon creation

## Response

**Status Code:** `200 OK`

**Content-Type:** `application/json`

### Response Schema

| Field         | Type           | Description                                   |
| ------------- | -------------- | --------------------------------------------- |
| `id`          | string (UUID)  | Unique identifier for the voice record        |
| `voice_id`    | string         | Voice identifier used in API calls            |
| `name`        | string         | Name of the cloned voice                      |
| `description` | string \| null | Description of the voice                      |
| `gender`      | string \| null | Gender of the voice                           |
| `age`         | string \| null | Age category of the voice                     |
| `languages`   | string\[]      | List of language codes supported by the voice |
| `dialect`     | string\[]      | List of dialects supported by the voice       |
| `type`        | string \| null | Voice type                                    |
| `sample_url`  | string         | URL to the sample audio file                  |
| `avatar_url`  | string \| null | URL to the avatar image                       |
| `stability`   | number         | Voice stability value                         |

### Example Response

```json theme={null}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "voice_id": "ar-cloned-voice-1",
  "name": "My Cloned Voice",
  "description": "A custom cloned voice",
  "gender": "male",
  "age": "middle",
  "languages": ["ar", "en"],
  "dialect": ["najdi"],
  "type": "neural",
  "sample_url": "https://example.com/voices/user123/ar-cloned-voice-1.wav",
  "avatar_url": null,
  "stability": 0.8
}
```

### Error Responses

**400 Bad Request**

```json theme={null}
{
  "errorCode": "400xx",
  "errorMessage": "voice_file is required and must be a file"
}
```

```json theme={null}
{
  "errorCode": "400xx",
  "errorMessage": "reference_audio_file is required and must be a file"
}
```

```json theme={null}
{
  "errorCode": "400xx",
  "errorMessage": "name is required"
}
```

```json theme={null}
{
  "errorCode": "400xx",
  "errorMessage": "text is required"
}
```

```json theme={null}
{
  "errorCode": "400xx",
  "errorMessage": "stability must be a number between 0 and 1"
}
```

```json theme={null}
{
  "errorCode": "400xx",
  "errorMessage": "model is required"
}
```

**401 Unauthorized**

```json theme={null}
{
  "errorCode": "40101",
  "errorMessage": "Invalid or missing API key"
}
```

**500 Internal Server Error**

```json theme={null}
{
  "errorCode": "50001",
  "errorMessage": "Failed to process voice file"
}
```

```json theme={null}
{
  "errorCode": "50001",
  "errorMessage": "Failed to upload voice file"
}
```

## Example Usage

### JavaScript

```javascript theme={null}
const formData = new FormData();
const voiceFile = document.querySelector('input[name="voice_file"]').files[0];
const referenceAudioFile = document.querySelector('input[name="reference_audio_file"]').files[0];

formData.append("voice_file", voiceFile);
formData.append("reference_audio_file", referenceAudioFile);
formData.append("text", "مرحبا بك في فصيح، هذا صوتي المستنسخ");
formData.append("stability", "0.8");
formData.append("name", "My Cloned Voice");
formData.append("model", "faseeh-v1-preview");
formData.append("description", "A custom cloned voice");
formData.append("gender", "male");
formData.append("languages", "ar,en");
formData.append("dialects", "najdi");

const response = await fetch('https://api.faseeh.ai/api/v1/voices/clone', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    // Note: Content-Type is set automatically by FormData
  },
  body: formData,
});

if (response.ok) {
  const voice = await response.json();
  console.log('Voice created:', voice.voice_id);
} else {
  const error = await response.json();
  console.error('Error:', error);
}
```

### Python

```python theme={null}
import requests

url = "https://api.faseeh.ai/api/v1/voices/clone"
headers = {
    "x-api-key": "YOUR_API_KEY"
}

files = {
    "voice_file": open("voice_sample.wav", "rb"),
    "reference_audio_file": open("reference_audio.wav", "rb")
}

data = {
    "text": "مرحبا بك في فصيح، هذا صوتي المستنسخ",
    "stability": "0.8",
    "name": "My Cloned Voice",
    "model": "faseeh-v1-preview",
    "description": "A custom cloned voice",
    "gender": "male",
    "languages": "ar,en",
    "dialects": "najdi"
}

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

if response.status_code == 200:
    voice = response.json()
    print(f"Voice created: {voice['voice_id']}")
else:
    print(f"Error: {response.status_code} - {response.text}")
```

### cURL

```bash theme={null}
curl -X POST "https://api.faseeh.ai/api/v1/voices/clone" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "voice_file=@voice_sample.wav" \
  -F "reference_audio_file=@reference_audio.wav" \
  -F "text=مرحبا بك في فصيح، هذا صوتي المستنسخ" \
  -F "stability=0.8" \
  -F "name=My Cloned Voice" \
  -F "model=faseeh-v1-preview" \
  -F "description=A custom cloned voice" \
  -F "gender=male" \
  -F "languages=ar,en" \
  -F "dialects=najdi"
```

<Note>
  **Voice Creation**: After cloning a voice, you can use the returned `voice_id` in text-to-speech generation endpoints. The voice will be available immediately after successful creation.
</Note>


# Voice Preview
Source: https://docs.faseeh.ai/api-reference/voice-preview

POST /voices/preview
Generate a preview of a voice you want to clone. This API allows you to test how a voice will sound before creating it as a permanent voice.

## Authentication

Requires API key authentication via `x-api-key` header.

## Request

**Content-Type:** `multipart/form-data`

### Form Data

| Field        | Type   | Required | Description                                                                                      |
| ------------ | ------ | -------- | ------------------------------------------------------------------------------------------------ |
| `text`       | string | Yes      | Text to generate preview with (minimum 3 words, 10 characters)                                   |
| `similarity` | number | Yes      | Voice similarity to source (0.0 to 1.0). Higher values produce more similar voice                |
| `model_id`   | string | Yes      | The model identifier to use for generation                                                       |
| `speed`      | number | No       | Speech speed (0.7 to 1.2, default 1.0). Values below 1.0 slow down speech, above 1.0 speed it up |
| `file`       | File   | Yes      | Audio file containing the voice to preview                                                       |

### Notes

* The API will process the provided audio file to generate the voice preview
* `text` must be at least 3 words and 10 characters long

## Response

**Status Code:** `200 OK`

**Headers:**

* `Content-Type: audio/raw;codec=pcm16;rate=24000;channels=1`
* `Cache-Control: no-cache`
* `Connection: keep-alive`

**Body:** Streaming PCM16 audio (24000 Hz, Mono, 16-bit)

### Error Responses

**400 Bad Request**

```json theme={null}
{
  "errorCode": "400xx",
  "errorMessage": "text is required"
}
```

```json theme={null}
{
  "errorCode": "400xx",
  "errorMessage": "similarity must be a number between 0 and 1"
}
```

```json theme={null}
{
  "errorCode": "400xx",
  "errorMessage": "speed must be a number between 0.7 and 1.2"
}
```

```json theme={null}
{
  "errorCode": "400xx",
  "errorMessage": "model_id is required"
}
```

```json theme={null}
{
  "errorCode": "400xx",
  "errorMessage": "file is required and must be of audio type"
}
```

**401 Unauthorized**

```json theme={null}
{
  "errorCode": "40101",
  "errorMessage": "Invalid or missing API key"
}
```

**402 Payment Required**

```json theme={null}
{
  "errorCode": "40201",
  "errorMessage": "Insufficient wallet balance"
}
```

**500 Internal Server Error**

```json theme={null}
{
  "errorCode": "50001",
  "errorMessage": "Failed to generate voice preview"
}
```

## Example Usage

### JavaScript

```javascript theme={null}
const formData = new FormData();
const audioFile = document.querySelector('input[type="file"]').files[0];
formData.append("file", audioFile);
formData.append("text", "مرحبا بك في فصيح، هذا صوتي الجديد");
formData.append("similarity", "0.8");
formData.append("model_id", "faseeh-v1-preview");
formData.append("speed", "1.0");

const response = await fetch('https://api.faseeh.ai/api/v1/voices/preview', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    // Note: Content-Type is set automatically by FormData
  },
  body: formData,
});

if (response.ok) {
  // Handle streaming audio response
  const reader = response.body.getReader();
  const audioChunks = [];
  
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    audioChunks.push(value);
  }
  
  // Combine chunks and create audio blob
  const audioBlob = new Blob(audioChunks, { type: 'audio/raw' });
  const audioUrl = URL.createObjectURL(audioBlob);
  // Use audioUrl to play the preview
} else {
  const error = await response.json();
  console.error('Error:', error);
}
```

### Python

```python theme={null}
import requests

url = "https://api.faseeh.ai/api/v1/voices/preview"
headers = {
    "x-api-key": "YOUR_API_KEY"
}

with open("source_audio.wav", "rb") as audio_file:
    files = {"file": audio_file}
    data = {
        "text": "مرحبا بك في فصيح، هذا صوتي الجديد",
        "similarity": "0.8",
        "model_id": "faseeh-v1-preview",
        "speed": "1.0"
    }
    response = requests.post(url, files=files, data=data, headers=headers, stream=True)

if response.status_code == 200:
    # Save streaming audio
    with open("voice_preview.pcm", "wb") as f:
        for chunk in response.iter_content(chunk_size=8192):
            f.write(chunk)
    print("Voice preview saved successfully")
else:
    print(f"Error: {response.status_code} - {response.text}")
```

### cURL

```bash theme={null}
curl -X POST "https://api.faseeh.ai/api/v1/voices/preview" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@source_audio.wav" \
  -F "text=مرحبا بك في فصيح، هذا صوتي الجديد" \
  -F "similarity=0.8" \
  -F "model_id=faseeh-v1-preview" \
  -F "speed=1.0" \
  --output voice_preview.pcm
```

<Note>
  **Voice Preview**: This endpoint generates a preview of a cloned voice. If you're satisfied with the preview, you can proceed to create it as a permanent voice using the voice creation endpoint.
</Note>


# Get Voices
Source: https://docs.faseeh.ai/api-reference/voices

GET /voices
Retrieve a list of all available voices for text-to-speech synthesis

Retrieve a list of all available voices for text-to-speech synthesis.

## Authentication

Requires API key authentication via `x-api-key` header.

## Response

Returns an array of voice objects.

### Response Schema

Each voice object contains:

| Field         | Type           | Description                                                                     |
| ------------- | -------------- | ------------------------------------------------------------------------------- |
| `voice_id`    | string         | Unique identifier for the voice (used in text-to-speech requests)               |
| `name`        | string         | Human-readable name of the voice                                                |
| `description` | string \| null | Detailed description of the voice characteristics                               |
| `gender`      | string \| null | Gender of the voice (`male`, `female`, or `null`)                               |
| `age`         | string \| null | Age category of the voice (`middle`, `elderly`, or `null`)                      |
| `languages`   | array\[string] | List of language codes supported by the voice (e.g., `["ar", "en"]`)            |
| `dialect`     | array\[string] | List of dialects supported by the voice (e.g., `["fusha", "emirati", "najdi"]`) |
| `type`        | string \| null | Voice type (`neural` or `null`)                                                 |
| `sample_url`  | string         | URL to an audio sample of the voice                                             |

## Usage

Use the `voice_id` from the response in text-to-speech generation endpoints:

* `POST /text-to-speech/:model_id` - Include `voice_id` in the request body
* `WS /text-to-speech` - Include `voice_id` in the WebSocket message

## Voice Types

Voices can be categorized by:

* **Dialect**: `fusha` (Modern Standard Arabic), `emirati`, `najdi`, `hijazi`, `kuwaiti`, `egyptian`, `british`, etc.
* **Gender**: `male` or `female`
* **Age**: `middle` or `elderly`
* **Languages**: Supported language codes (e.g., `ar` for Arabic, `en` for English)

<Note>
  **Custom Voices**: Some voices may have `null` values for certain fields. These are typically custom user-created voices. The `voice_id` can still be used in text-to-speech requests regardless of these field values.
</Note>

<Note>
  **Caching**: Voice information doesn't change frequently. Consider caching the voice list to reduce API calls and improve application performance.
</Note>


# Text-To-Speech WebSocket
Source: https://docs.faseeh.ai/api-reference/websocket



The Text-to-Speech WebSocket API is designed to generate audio from partial text input while ensuring consistency throughout the generated audio. Although highly flexible, the WebSocket API isn't a one-size-fits-all solution. It's well-suited for scenarios where:

* The input text is being streamed or generated in chunks.
* Real-time audio generation is required with low latency.
* You need to send text incrementally as it becomes available.

However, it may not be the best choice when:

* The entire input text is available upfront. Given that the generations are partial, some buffering is involved, which could potentially result in slightly higher latency compared to a standard HTTP request.
* You want to quickly experiment or prototype. Working with WebSockets can be harder and more complex than using a standard HTTP API, which might slow down rapid development and testing.

## Endpoint

```
WSS /websocket/text-to-speech
```

## Connection URL

```
wss://api.faseeh.ai/api/v1/websocket/text-to-speech?x-api-key=YOUR_API_KEY
```

## Authentication

Requires API key authentication via `x-api-key` query parameter or in the initial connection message.

## Query Parameters

| Parameter   | Type   | Required | Description         |
| ----------- | ------ | -------- | ------------------- |
| `x-api-key` | string | Yes      | Your Faseeh API key |

## Message Types

### Initialize Connection

After establishing the WebSocket connection, you must send an initialization message.

**Request**:

```json theme={null}
{
  "type": "initConnection",
  "model_id": "faseeh-v1-preview",
  "voice_id": "ar-najdi-male-2",
  "voice_settings": {
    "stability": 0.5,
    "similarity_boost": 0.75,
    "speed": 1.0
  },
  "output_format": "pcm_24000",
  "x_api_key": "YOUR_API_KEY"
}
```

**Request Fields**:

| Field                             | Type   | Required | Description                                                                                                      |
| --------------------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `type`                            | string | Yes      | Must be `"initConnection"`                                                                                       |
| `model_id`                        | string | No       | Model ID to use (default: `"faseeh-mini-v1-preview"`)                                                            |
| `voice_id`                        | string | Yes      | The voice ID to use for synthesis                                                                                |
| `voice_settings`                  | object | No       | Voice configuration                                                                                              |
| `voice_settings.stability`        | number | No       | Stability setting (default: 0.5)                                                                                 |
| `voice_settings.similarity_boost` | number | No       | Similarity boost (default: 0.75)                                                                                 |
| `voice_settings.speed`            | number | No       | Speed setting, range 0.7-1.2 (default: 1.0)                                                                      |
| `output_format`                   | string | No       | Audio output format. Options: `"pcm_8000"`, `"pcm_16000"`, `"pcm_22050"`, `"pcm_24000"` (default: `"pcm_24000"`) |
| `x_api_key`                       | string | No       | API key (if not provided in query parameter)                                                                     |

**Response**:

```json theme={null}
{
  "type": "connectionInitialized"
}
```

### Send Text

Send text chunks for audio generation.

**Request**:

```json theme={null}
{
  "type": "text",
  "text": "مرحبا بك في فصيح ",
  "flush": false,
  "try_trigger_generation": false
}
```

**Request Fields**:

| Field                    | Type    | Required | Description                                                          |
| ------------------------ | ------- | -------- | -------------------------------------------------------------------- |
| `type`                   | string  | Yes      | Must be `"text"`                                                     |
| `text`                   | string  | Yes      | Text to convert to speech                                            |
| `flush`                  | boolean | No       | Force generation of audio even if buffer is small (default: `false`) |
| `try_trigger_generation` | boolean | No       | Attempt to trigger generation immediately (default: `false`)         |

**Response**:

```json theme={null}
{
  "audio": "base64_encoded_audio_data",
  "sampleRate": 24000
}
```

**Response Fields**:

| Field        | Type   | Description                                   |
| ------------ | ------ | --------------------------------------------- |
| `audio`      | string | Base64-encoded PCM audio data                 |
| `sampleRate` | number | Sample rate of the audio (typically 24000 Hz) |

### Clear Buffer

Clear the current text buffer.

**Request**:

```json theme={null}
{
  "type": "clear"
}
```

**Response**: No response message.

### Close Connection

Close the WebSocket connection gracefully.

**Request**:

```json theme={null}
{
  "type": "closeConnection"
}
```

**Response**: Connection closes.

## Error Responses

If an error occurs, you'll receive:

```json theme={null}
{
  "type": "error",
  "errorCode": 40101,
  "errorMessage": "Invalid API key"
}
```

**Error Response Fields**:

| Field          | Type   | Description                             |
| -------------- | ------ | --------------------------------------- |
| `type`         | string | Always `"error"`                        |
| `errorCode`    | number | Numeric error code (e.g., 40101, 40001) |
| `errorMessage` | string | Human-readable error message            |

## Example Usage

```javascript theme={null}
const ws = new WebSocket('wss://api.faseeh.ai/api/v1/websocket/text-to-speech?x-api-key=YOUR_API_KEY');

ws.onopen = () => {
  // Initialize connection
  ws.send(JSON.stringify({
    type: "initConnection",
    model_id: "faseeh-v1-preview",
    voice_id: "ar-najdi-male-2",
    voice_settings: {
      stability: 0.5,
      similarity_boost: 0.75,
      speed: 1.0
    },
    output_format: "pcm_24000"
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  
  if (data.type === "connectionInitialized") {
    // Connection ready, send text
    ws.send(JSON.stringify({
      type: "text",
      text: "مرحبا بك في فصيح "
    }));
  } else if (data.audio) {
    // Process audio chunk
    const audioData = atob(data.audio);
    // Handle audio playback
  } else if (data.type === "error" || data.errorCode) {
    console.error("Error:", data.errorMessage);
  }
};

ws.onerror = (error) => {
  console.error("WebSocket error:", error);
};

ws.onclose = () => {
  console.log("WebSocket closed");
};
```

## Best Practices

1. **Always initialize**: Send `initConnection` immediately after opening the connection
2. **Handle errors**: Check for error messages in responses
3. **Flush when done**: Use `flush: true` when sending the last text chunk to ensure all audio is generated
4. **Close gracefully**: Send `closeConnection` before closing the WebSocket
5. **Buffer audio**: Collect audio chunks and play them sequentially for smooth playback


# Speech to Text
Source: https://docs.faseeh.ai/capabilities/speech-to-text

Transcribe spoken Arabic audio into text

Faseeh's Speech-to-Text API converts spoken Arabic audio into accurate text transcriptions, supporting multiple dialects and providing precise word-level timestamps.

## Overview

The Speech-to-Text capability enables you to:

* Transcribe Arabic audio in real-time
* Support multiple Arabic dialects
* Get accurate transcriptions with timestamps
* Handle speaker diarization (coming soon)

## Features

<CardGroup>
  <Card>
    <div>
      <div>
        <div>
          Multi-Dialect Support
        </div>

        <p>
          Accurate transcription across Arabic dialects
        </p>
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <div>
        <div>
          Real-time Processing
        </div>

        <p>
          Low-latency transcription for live applications
        </p>
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <div>
        <div>
          Word-level Timestamps
        </div>

        <p>
          Precise timing information for each word
        </p>
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <div>
        <div>
          High Accuracy
        </div>

        <p>
          State-of-the-art Arabic speech recognition
        </p>
      </div>
    </div>
  </Card>
</CardGroup>

## Coming Soon

Speech-to-Text capabilities are currently under development. Check back soon for API endpoints and documentation.

<Note>
  **Status**: Speech-to-Text API endpoints will be available in a future release. Stay tuned for updates!
</Note>


# Voice Cloning
Source: https://docs.faseeh.ai/capabilities/voice-cloning

Clone and design custom Arabic voices

Faseeh's Voice Cloning technology allows you to create custom Arabic voices from audio samples, enabling personalized voice synthesis for your applications.

## Overview

Voice Cloning enables you to:

* Create custom voices from audio samples
* Clone voices in various Arabic dialects
* Use cloned voices in text-to-speech generation
* Manage your voice library

## Features

<CardGroup>
  <Card>
    <div>
      <div>
        <div>
          High-Quality Cloning
        </div>

        <p>
          Create lifelike voice clones from short audio samples
        </p>
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <div>
        <div>
          Multi-Dialect Support
        </div>

        <p>
          Clone voices across different Arabic dialects
        </p>
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <div>
        <div>
          Voice Library
        </div>

        <p>
          Manage and organize your custom voices
        </p>
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <div>
        <div>
          Easy Integration
        </div>

        <p>
          Use cloned voices seamlessly with TTS API
        </p>
      </div>
    </div>
  </Card>
</CardGroup>

## Voice Cloning Process

1. **Upload Audio Sample**: Provide a high-quality audio sample of the voice you want to clone
2. **Processing**: Faseeh processes the sample and creates a voice model
3. **Voice ID**: Receive a unique voice ID for your cloned voice
4. **Use in TTS**: Use the voice ID in text-to-speech generation requests

## Best Practices

* **Audio Quality**: Use high-quality audio samples (minimum 1 minute recommended)
* **Clear Speech**: Ensure the audio contains clear, natural speech
* **Consistent Environment**: Record in a quiet environment with minimal background noise
* **Multiple Samples**: Provide multiple samples for better voice quality

## Coming Soon

Voice Cloning API endpoints are currently under development. Check back soon for detailed API documentation.

<Note>
  **Status**: Voice Cloning API endpoints will be available in a future release. Stay tuned for updates!
</Note>


# Voice Isolation
Source: https://docs.faseeh.ai/capabilities/voice-isolation

Isolate voices from background noise

Faseeh's Voice Isolation technology separates clean speech from background noise, improving audio quality for transcription and voice cloning applications.

## Overview

Voice Isolation helps you:

* Remove background noise from audio recordings
* Enhance speech clarity for better transcription
* Prepare clean audio for voice cloning
* Improve audio quality for downstream processing

## Features

<CardGroup>
  <Card>
    <div>
      <div>
        <div>
          Advanced Noise Reduction
        </div>

        <p>
          AI-powered noise removal while preserving speech quality
        </p>
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <div>
        <div>
          Real-time Processing
        </div>

        <p>
          Low-latency isolation for live audio streams
        </p>
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <div>
        <div>
          Multi-Speaker Support
        </div>

        <p>
          Isolate individual speakers in multi-speaker recordings
        </p>
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <div>
        <div>
          High Fidelity
        </div>

        <p>
          Maintains natural speech characteristics
        </p>
      </div>
    </div>
  </Card>
</CardGroup>

## Use Cases

* **Pre-processing for Transcription**: Clean audio before sending to speech-to-text
* **Voice Cloning Preparation**: Isolate clean speech for better voice cloning results
* **Podcast Production**: Remove background noise from podcast recordings
* **Call Quality Enhancement**: Improve audio quality in telephony applications

## Coming Soon

Voice Isolation API endpoints are currently under development. Check back soon for detailed API documentation.

<Note>
  **Status**: Voice Isolation API endpoints will be available in a future release. Stay tuned for updates!
</Note>


# Self Hosting
Source: https://docs.faseeh.ai/docs/capabilities/on



## **Introduction**

On-prem deployment allows you to run **FASEEH** entirely within your own infrastructure—inside your data center or private environment. This option is built for enterprises and regulated industries that require full control over data, security, and performance.

By removing dependency on public networks, on-prem deployments deliver predictable latency, strong governance, and guaranteed data sovereignty.

FASEEH delivers **native Arabic speech perfected for the GCC and MENA region—without compromise in English quality**, making it suitable for both local and global use cases.

## **Why On-Premises?**

### **🔹  Ultra-Low Latency**

Local deployment eliminates internet round-trips, enabling **sub-100ms latency** for real-time voice and conversational workloads.

### **🔹 Data Residency & Compliance**

All data remains inside your controlled environment—ideal for banking, healthcare, telecom, and government deployments.

### **🔹 Full Infrastructure Control**

You control infrastructure sizing, scaling, networking, security policies, and upgrade cycles, aligned with internal IT and compliance standards.

<img alt="Canvas Image 1 1768219755658" />

## **Security**

On-prem deployment ensures **zero data transmission over the public internet**.

* Customer data stays fully within your network
* Integrates with internal IAM, firewalls, and security tooling
* Supports strict privacy, audit, and regulatory requirements

Built for environments where data control is non-negotiable.

## **Performance**

FASEEH on-prem is optimized for production-grade, real-time workloads.

* **Sub-100ms median latency** for short to mid-length utterances
* Stable, predictable performance under high concurrency
* Optimized for conversational AI, voice agents, and real-time applications
* High naturalness in both **Arabic (GCC-native dialects)** and **English**

Actual performance depends on deployment configuration, concurrency, and tuning.

## **Models Available**

FASEEH on-prem supports two production-ready models:

### **FASEEH Large**

* Superior prosody and naturalness
* Best-in-class voice cloning and dubbing quality
* Fewer pronunciation and expression errors
* Ideal for media, dubbing, premium voice agents, and high-fidelity use cases

### **FASEEH Mini**

* Faster and more cost-efficient
* Delivers \~**90% of FASEEH Large quality**
* Optimized for scale and high-concurrency deployments
* Ideal for conversational AI, call centers, and enterprise automation

## **Deployment Support**

Actualize supports on-prem deployments across:

* Customer-owned data centers
* Private environments
* Cloud providers using dedicated or isolated infrastructure

We assist with **hardware procurement, provisioning, and setup**, whether machines run on-prem or in supported cloud environments.

Actualize is a **Microsoft Partner**, enabling aligned enterprise deployments with Microsoft ecosystem tooling, governance, and support where required.

## **When to Choose On-Prem**

Choose on-prem deployment if you require:

* Guaranteed data residency
* Regulatory compliance
* Predictable, ultra-low latency
* Deep integration with internal systems
* Long-term scalability under your control

## **Next Steps**

To proceed with an on-prem deployment:

* Validate hardware and capacity requirements
* Align on network and security prerequisites
* Contact the FASEEH team for deployment architecture and sizing guidance

📩 **Reach out:** [**support@faseeh.ai**](mailto:support@faseeh.ai)

Enterprise support and tailored deployment options are available.


# Data Privacy Compliance
Source: https://docs.faseeh.ai/docs/getting-started/complaince



### **Compliance & Data Privacy**

FASEEH is built to meet the requirements of **regulated, production-grade Voice AI systems**, where data privacy, security, and control are non-negotiable.

### **HIPAA Compliance**

FASEEH supports **HIPAA-compliant deployments** through an explicit **HIPAA Mode**.

When HIPAA Mode is enabled:

* No call recordings are stored on FASEEH servers
* Audio streams are processed in-memory only
* Zero persistent storage of voice data
* All data ownership remains with the customer
* No secondary usage of audio for training or analytics

This enables Voice AI companies and enterprises to confidently use FASEEH for healthcare, financial services, government, and regulated enterprise workloads without compromising compliance.

HIPAA Mode is available across **SaaS, Dedicated VPC, and On-Prem deployments**.

**Data Ownership & Control**

FASEEH follows a **customer-first data model**:

* Customers retain **full ownership** of all audio, transcripts, and metadata
* No recordings are retained unless explicitly configured by the customer
* Deployment-level controls determine retention, logging, and access policies
* Suitable for **air-gapped and sovereign environments**

### **Security & Certifications**

FASEEH is designed with enterprise security standards from day one.

* **HIPAA** — Certified
* **SOC 2** — *in progress*
* **ISO 27001** — *in progress*

Security controls already implemented include:

* Strict access isolation per tenant
* Encrypted data in transit
* Environment-level security boundaries (SaaS, VPC, On-Prem)
* Operational auditability for enterprise customers

### **Built for Regulated Voice AI**

FASEEH is trusted in environments where:

* Voice data is sensitive by default
* Retention must be explicitly disabled
* Infrastructure must support **on-prem or sovereign hosting**
* Compliance is enforced at the **architecture level**, not through policy documents

FASEEH enables teams to build **real-time Voice AI systems** with confidence — without sacrificing privacy, performance, or control.

### Customer Responsibility

Customers are **solely responsible** for:

* The content generated by applications using FASEEH
* Ensuring generated outputs comply with applicable laws, regulations, and industry standards
* Implementing appropriate human review, guardrails, and usage policies where required

FASEEH provides the underlying speech and inference infrastructure but does not control, moderate, or assume responsibility for customer-generated content.


# Support
Source: https://docs.faseeh.ai/docs/getting-started/support



**Getting Help with FASEEH**

If you need help integrating, deploying, or troubleshooting FASEEH, our team is here to assist.\
\
**Contact Support**

<CardGroup>
  <Card title="Email Support" icon="envelope">
    Email [support@faseeh.ai](mailto:support@faseeh.ai) with your request and our team will get back to you promptly.

    You can expect a response within **48–72 hours**.
  </Card>
</CardGroup>

## **What We Can Help With**

* API usage and integration questions
* Deployment support (SaaS, dedicated, or on-prem)
* Performance or quality issues
* Configuration and setup guidance
* Account and access-related queries

Please include relevant details such as request IDs, timestamps, deployment type, and a brief description of the issue to help us respond faster.

## **Support Plans**

**If your organization has an Enterprise or contracted support plan, your request will be handled according to your agreed SLA.**

If you are using FASEEH without a contracted support plan, you can still reach out via email and our team will assist on a best-effort basis.

We’re committed to making sure FASEEH runs reliably in production—especially for enterprise and regulated environments.


# Introduction
Source: https://docs.faseeh.ai/index

Faseeh - First True Arabic Voice AI that speaks Dialects From Abu Dhabi to Rabat with Voice Cloning & On-prem support

## Resources

<CardGroup>
  <Card title="Text-to-speech" icon="volume-high" href="/text-to-speech/get-started">
    Convert text into lifelike speech
  </Card>

  <Card title="Self Hosting" icon="server" href="/docs/capabilities/on">
    Deploy Faseeh on your own infrastructure
  </Card>

  <Card title="Data Privacy Compliance" icon="shield-check" href="/docs/getting-started/complaince">
    Learn about our compliance and data privacy standards
  </Card>

  <Card title="Support" icon="envelope" href="/docs/getting-started/support">
    Get help with Faseeh
  </Card>
</CardGroup>

<iframe title="YouTube video player" />

## Getting Started

Create an API Key in the [Faseeh dashboard](https://app.faseeh.ai/en/api-keys) to get started with our voice synthesis API.

<Card title="Start here" icon="rocket" href="/text-to-speech/get-started">
  Follow our quickstart guide to integrate Faseeh into your application.
</Card>


# LiveKit Plugin
Source: https://docs.faseeh.ai/integrations/livekit-plugin

Integrate Faseeh Arabic TTS with LiveKit voice agents

# Integrating Faseeh with LiveKit Agents

This tutorial will guide you through integrating Faseeh's Arabic text-to-speech into your LiveKit voice agents, enabling natural-sounding Arabic conversations in your real-time applications.

## Prerequisites

* A [Faseeh AI](https://app.faseeh.ai) account
* Python 3.9 or higher installed
* Basic familiarity with LiveKit Agents framework
* A LiveKit Cloud account (or self-hosted LiveKit server)

## API Key

Go to [Faseeh - API Keys](https://app.faseeh.ai/en/api-keys), Generate an API key, then save it securely.

<Warning>
  Your API key is only shown once. Save it securely.
</Warning>

## Installation

Install the Faseeh plugin for LiveKit Agents:

```bash theme={null}
pip install livekit-plugins-faseeh
```

For development or testing from source:

```bash theme={null}
git clone https://github.com/actualize-ae/livekit-plugins-faseeh.git
cd livekit-plugins-faseeh
pip install -e .
```

## Step 3: Set Up Your Environment

Create a `.env.local` file in your project directory to store your API keys securely:

```bash theme={null}
# Faseeh Configuration
FASEEH_API_KEY=your_faseeh_api_key_here

# LiveKit Configuration
LIVEKIT_URL=wss://your-livekit-server.com
LIVEKIT_API_KEY=your_livekit_api_key
LIVEKIT_API_SECRET=your_livekit_api_secret

# LLM Configuration (for the agent's brain)
OPENAI_API_KEY=your_openai_api_key

# Optional: Deepgram for Arabic STT
DEEPGRAM_API_KEY=your_deepgram_api_key
```

## Step 4: Create Your First Arabic Voice Agent

Create a file called `arabic_agent.py`:

```python theme={null}
"""
Simple Arabic Voice Assistant using Faseeh TTS
"""
from dotenv import load_dotenv
from livekit import agents
from livekit.agents import AgentServer, AgentSession, Agent
from livekit.plugins import silero, deepgram, openai, faseeh

# Load environment variables
load_dotenv(".env.local")


class ArabicAssistant(Agent):
    """Arabic-speaking voice assistant"""

    def __init__(self) -> None:
        super().__init__(
            instructions="""أنت مساعد صوتي ذكي يتحدث العربية بطلاقة.
            مهمتك مساعدة المستخدمين بالإجابة على أسئلتهم بطريقة واضحة ومفيدة.
            كن ودوداً ومحترماً في تعاملك."""
        )


# Create the agent server
server = AgentServer()


@server.rtc_session()
async def my_agent(ctx: agents.JobContext):
    """Entry point for each agent session"""

    # Configure Faseeh TTS
    faseeh_tts = faseeh.TTS(
        voice_id="ar-uae-male-1",           # Choose your voice
        model="faseeh-v1-preview",          # Use full model for best quality
        stability=0.75,                     # Balanced stability
        speed=1.0,                          # Normal speech speed (0.7-1.2)
    )

    # Create agent session with all components
    session = AgentSession(
        stt=openai.STT(),
        llm=openai.LLM(                     # Language model
            model="gpt-4o",
            temperature=0.7
        ),
        tts=faseeh_tts,                     # Faseeh for Arabic speech
        vad=silero.VAD.load(),              # Voice activity detection
    )

    # Start the session
    await session.start(
        room=ctx.room,
        agent=ArabicAssistant()
    )

    # Generate initial greeting
    await session.generate_reply(
        instructions="رحب بالمستخدم باللغة العربية وقدم نفسك كمساعد ذكي جاهز للمساعدة."
    )


if __name__ == "__main__":
    agents.cli.run_app(server)
```

## Step 5: Run Your Agent

### Development Mode

For local testing with LiveKit's dev server:

```bash theme={null}
python arabic_agent.py dev
```

This will:

1. Start a local LiveKit server
2. Launch your agent
3. Provide a test URL you can open in your browser

### Production Mode

For deployment with your LiveKit Cloud or self-hosted server:

```bash theme={null}
python arabic_agent.py start
```

Make sure your LiveKit credentials are properly configured in `.env.local`.

## Step 6: Test Your Agent

1. Open the provided URL in your web browser
2. Allow microphone access when prompted
3. Speak in Arabic - the agent will respond using Faseeh's natural-sounding voice
4. Try different questions to test the conversation flow

## Configuration Options

### Available Voice IDs

To choose a voice for your agent:

1. Visit the [Faseeh Voice Library](https://app.faseeh.ai/en/voices)
2. Listen to different voices to find the one that best fits your use case
3. Click **"Copy Voice ID"** button next to your chosen voice
4. Use that voice ID in your code:

```python theme={null}
faseeh_tts = faseeh.TTS(
    voice_id="ar-uae-male-1",  # Paste the copied voice ID here
    model="faseeh-v1-preview",
    speed=1.0                  # Speech speed (0.7-1.2)
)
```

### Model Selection

Choose between two models based on your needs:

```python theme={null}
# Full model - Best quality, slightly higher latency
faseeh_tts = faseeh.TTS(
    model="faseeh-v1-preview",
    stability=0.75,
    speed=1.0
)

# Mini model - Faster, lower latency, good quality
faseeh_tts = faseeh.TTS(
    model="faseeh-mini-v1-preview",
    stability=0.75,
    speed=1.0
)
```

### Stability Parameter

The `stability` parameter controls voice consistency:

* **0.0 - 0.4**: More expressive, creative, but can hallucinate
* **0.5 - 0.7**: Balanced (recommended for most use cases)
* **0.8 - 1.0**: Very consistent, less variation

```python theme={null}
# Dynamic voice - More expressive
faseeh_tts = faseeh.TTS(stability=0.4, speed=1.0)

# Consistent voice - Professional applications
faseeh_tts = faseeh.TTS(stability=0.9, speed=1.0)
```

### Speed Parameter

The `speed` parameter controls speech rate:

* **0.7 - 0.9**: Slower speech (clearer for complex content)
* **1.0**: Normal speed (default)
* **1.1 - 1.2**: Faster speech (for quick responses)

```python theme={null}
# Slower speech - For clear enunciation
faseeh_tts = faseeh.TTS(stability=0.75, speed=0.8)

# Faster speech - For rapid delivery
faseeh_tts = faseeh.TTS(stability=0.75, speed=1.2)
```

### Dynamic Voice Switching

You can change voice settings during runtime:

```python theme={null}
# Start with one voice
faseeh_tts = faseeh.TTS(voice_id="ar-uae-male-1", speed=1.0)

# Switch to a different voice based on context
faseeh_tts.update_options(
    voice_id="ar-hijazi-female-2",
    stability=0.8,
    speed=1.0
)
```

## Advanced Features

### Bilingual Support

Create agents that can switch between Arabic and English:

```python theme={null}
class BilingualAssistant(Agent):
    def __init__(self) -> None:
        super().__init__(
            instructions="""You are a bilingual AI assistant fluent in both Arabic and English.
            Automatically detect the user's language and respond in the same language.
            If the user speaks Arabic, respond in Arabic using natural expressions.
            If the user speaks English, respond in English."""
        )

@server.rtc_session()
async def bilingual_agent(ctx: agents.JobContext):
    session = AgentSession(
        stt=deepgram.STT(
            language="multi",  # Multi-language support
            model="nova-2-general"
        ),
        llm=openai.LLM(model="gpt-4o-mini"),
        tts=faseeh.TTS(
            voice_id="ar-uae-male-1",
            model="faseeh-v1-preview",
            speed=1.0
        ),
        vad=silero.VAD.load(),
    )

    await session.start(room=ctx.room, agent=BilingualAssistant())
```

### Streaming for Low Latency

Faseeh supports streaming for real-time applications:

```python theme={null}
# Streaming is automatically enabled
# The agent will start speaking as soon as the first audio chunk is ready
faseeh_tts = faseeh.TTS(
    model="faseeh-mini-v1-preview",  # Mini model for even lower latency
    stability=0.6,
    speed=1.0
)
```

## Monitoring and Metrics

Track your agent's performance:

```python theme={null}
from livekit.agents.metrics import TTSMetrics
import logging

logger = logging.getLogger("faseeh_agent")

@session.on("metrics_collected")
def _on_metrics_collected(event):
    metrics = event.metrics

    if isinstance(metrics, TTSMetrics):
        logger.info(
            f"TTS Performance - "
            f"TTFB: {metrics.ttfb:.2f}s, "
            f"Audio Duration: {metrics.audio_duration:.2f}s"
        )
```

## Best Practices

### 1. API Key Security

✅ **DO:**

* Store API keys in `.env.local` (not committed to Git)
* Use environment variables in production
* Rotate keys periodically

❌ **DON'T:**

* Hardcode API keys in source code
* Commit `.env` files to version control
* Share API keys in chat or email

### 2. Stability Settings

* **Chatbots**: 0.6 - 0.8 (balanced and reliable)
* **Professional Applications**: 0.8 - 1.0 (very consistent)
* **Creative Content**: 0.3 - 0.5 (more expressive)

## Troubleshooting

### "Invalid API Key" Error

**Solution**: Double-check your API key in `.env.local`

```bash theme={null}
# Verify the key is set correctly
echo $FASEEH_API_KEY
```

### "Payment Required" Error

**Solution**: Your Faseeh account balance is low. Top up at [apps.faseeh.ai](https://apps.faseeh.ai)

### "Rate Limit Exceeded"

**Solution**: You're sending too many requests. Implement rate limiting or contact Faseeh support to increase your limits.

### No Audio Output

**Checklist:**

1. ✅ API key is valid
2. ✅ Network connection is stable
3. ✅ Microphone permissions are granted
4. ✅ Browser supports WebRTC
5. ✅ Firewall allows WebSocket connections

### Poor Audio Quality

**Solutions:**

* Switch to `faseeh-v1-preview` (full model)
* Increase stability to 0.8 or higher
* Check your network connection
* Ensure proper audio codec support

## Support

Need help?

* **Plugin Issues**: [GitHub Issues](https://github.com/actualize-ae/livekit-plugins-faseeh/issues)
* **Faseeh Support**: [Schedule a Meeting](https://www.actualize.pro/schedule)
* **LiveKit Support**: [LiveKit Community](https://livekit.io/community)

## License

This plugin is licensed under Apache License 2.0. See [LICENSE](https://github.com/actualize-ae/livekit-plugins-faseeh/blob/main/LICENSE) for details.


# Pipecat Plugin
Source: https://docs.faseeh.ai/integrations/pipecat-plugin

Build conversational Arabic AI agents with Pipecat and Faseeh TTS

## Overview

[Pipecat](https://github.com/pipecat-ai/pipecat) is an open-source Python framework for building real-time voice and multimodal conversational AI agents. The `pipecat-plugins-faseeh` package bridges Faseeh TTS into Pipecat pipelines, letting you build Arabic voice agents with low-latency streaming audio.

## Prerequisites

* A [Faseeh AI](https://app.faseeh.ai) account
* Python 3.9 or higher

## API Key

Go to [Faseeh - API Keys](https://app.faseeh.ai/en/api-keys), Generate an API key, then save it securely.

<Warning>
  Your API key is only shown once. Save it securely.
</Warning>

## Installation

```bash theme={null}
pip install pipecat-plugins-faseeh
```

## Quick Start

```python theme={null}
import aiohttp
from pipecat_plugins_faseeh import FaseehTTSService

async with aiohttp.ClientSession() as session:
    tts = FaseehTTSService(
        api_key="your-api-key",
        aiohttp_session=session,
    )
```

## Configuration Reference

| Parameter   | Type  | Default                        | Description                 |
| ----------- | ----- | ------------------------------ | --------------------------- |
| `api_key`   | str   | env `FASEEH_API_KEY`           | Faseeh API key              |
| `voice_id`  | str   | `ar-hijazi-female-2`           | Voice identifier            |
| `model`     | str   | `faseeh-v1-preview`            | TTS model                   |
| `stability` | float | 0.5                            | Voice consistency (0.0-1.0) |
| `speed`     | float | 1.0                            | Speech rate (0.7-1.2)       |
| `base_url`  | str   | `https://api.faseeh.ai/api/v1` | API base URL                |

### Available Voice IDs

To choose a voice for your agent:

1. Visit the [Faseeh Voice Library](https://app.faseeh.ai/en/voices)
2. Listen to different voices to find the one that best fits your use case
3. Click **"Copy Voice ID"** button next to your chosen voice
4. Use that voice ID in your code:

```python theme={null}
tts = FaseehTTSService(
    api_key="your-api-key",
    voice_id="ar-uae-male-1",  # Paste the copied voice ID here
    aiohttp_session=session,
)
```

## Pipeline Architecture

In a typical Pipecat pipeline, data flows through processors in sequence:

```
Microphone → Transport → STT → LLM → Faseeh TTS → Transport → Speaker
```

1. User speaks into the microphone
2. Transport (e.g., Daily WebRTC) captures audio
3. STT (e.g., Deepgram) converts speech to text
4. LLM (e.g., OpenAI GPT-4o) generates a response
5. **Faseeh TTS** converts the response to Arabic audio (streaming PCM16 at 24kHz)
6. Transport sends audio back to the user

Pipecat's `TTSService` base class aggregates LLM tokens into complete sentences before calling Faseeh. Each sentence triggers one HTTP streaming request to the Faseeh API, and PCM16 audio chunks are yielded back to the pipeline as they arrive.

## Full Example

```python theme={null}
import asyncio
import os

import aiohttp
from dotenv import load_dotenv

from pipecat.audio.vad.silero import SileroVADAnalyzer
from pipecat.frames.frames import EndFrame, LLMMessagesUpdateFrame
from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.runner import PipelineRunner
from pipecat.pipeline.task import PipelineParams, PipelineTask
from pipecat.processors.aggregators.llm_context import LLMContext
from pipecat.processors.aggregators.llm_response_universal import (
    LLMContextAggregatorPair,
    LLMUserAggregatorParams,
)
from pipecat.services.deepgram.stt import DeepgramSTTService
from pipecat.services.openai.llm import OpenAILLMService
from pipecat.transports.daily.transport import DailyParams, DailyTransport

from pipecat_plugins_faseeh import FaseehTTSService

load_dotenv(override=True)


async def main():
    async with aiohttp.ClientSession() as session:
        # Auto-create a Daily room
        from pipecat.transports.daily.utils import DailyRESTHelper, DailyRoomParams

        daily_helper = DailyRESTHelper(
            daily_api_key=os.getenv("DAILY_API_KEY", ""),
            aiohttp_session=session,
        )
        room = await daily_helper.create_room(DailyRoomParams())
        token = await daily_helper.get_token(room.url)

        transport = DailyTransport(
            room.url,
            token,
            "Faseeh Bot",
            DailyParams(
                audio_in_enabled=True,
                audio_out_enabled=True,
                audio_out_sample_rate=24000,
            ),
        )

        stt = DeepgramSTTService(api_key=os.getenv("DEEPGRAM_API_KEY", ""))
        llm = OpenAILLMService(api_key=os.getenv("OPENAI_API_KEY", ""), model="gpt-4o")
        tts = FaseehTTSService(
            api_key=os.getenv("FASEEH_API_KEY"),
            aiohttp_session=session,
        )

        messages = [
            {
                "role": "system",
                "content": "You are a helpful Arabic-speaking assistant. Respond in Arabic.",
            }
        ]
        context = LLMContext(messages=messages)
        context_aggregator = LLMContextAggregatorPair(
            context,
            user_params=LLMUserAggregatorParams(vad_analyzer=SileroVADAnalyzer()),
        )

        pipeline = Pipeline([
            transport.input(),
            stt,
            context_aggregator.user(),
            llm,
            tts,
            transport.output(),
            context_aggregator.assistant(),
        ])

        task = PipelineTask(pipeline, params=PipelineParams(allow_interruptions=True))

        @transport.event_handler("on_first_participant_joined")
        async def on_joined(transport, participant):
            await task.queue_frames([LLMMessagesUpdateFrame(messages, run_llm=True)])

        @transport.event_handler("on_participant_left")
        async def on_left(transport, participant, reason):
            await task.queue_frame(EndFrame())

        runner = PipelineRunner()
        await runner.run(task)


if __name__ == "__main__":
    asyncio.run(main())
```

## Runtime Configuration

Change voice, model, speed, or stability during an active conversation:

```python theme={null}
from pipecat.frames.frames import TTSUpdateSettingsFrame

# Switch voice
await task.queue_frame(TTSUpdateSettingsFrame(settings={"voice_id": "ar-emirati-male-1"}))

# Adjust speed and stability
await task.queue_frame(TTSUpdateSettingsFrame(settings={"speed": 1.1, "stability": 0.8}))

# Switch model
await task.queue_frame(TTSUpdateSettingsFrame(settings={"model": "faseeh-v2"}))
```

## Error Handling

The plugin yields non-fatal `ErrorFrame` objects instead of raising exceptions. This means your pipeline continues running even if a single TTS request fails.

Common errors:

| HTTP Status | Meaning                  | Action                       |
| ----------- | ------------------------ | ---------------------------- |
| 401         | Invalid API key          | Check `FASEEH_API_KEY`       |
| 402         | Insufficient balance     | Add credits at app.faseeh.ai |
| 404         | Voice or model not found | Check `voice_id` and `model` |
| 429         | Rate limit exceeded      | Reduce request frequency     |

Handle errors in your application:

```python theme={null}
from pipecat.frames.frames import ErrorFrame

@task.event_handler("on_error")
async def on_error(task, error: ErrorFrame):
    logger.error(f"TTS error: {error.error}")
```

## Troubleshooting

**No audio output?**

* Verify `FASEEH_API_KEY` is set and valid
* Ensure `voice_id` exists in the Faseeh voice library
* Check that the pipeline sample rate matches (24000 Hz default)

**High latency?**

* The plugin uses HTTP streaming by default for lowest latency
* Check network connectivity to `api.faseeh.ai`
* Consider using a voice with faster generation characteristics

**Import errors?**

* Ensure both `pipecat-ai` and `pipecat-plugins-faseeh` are installed
* Minimum Pipecat version: 0.0.100


# Ultravox Integration
Source: https://docs.faseeh.ai/integrations/ultravox-integration

Add a Custom FASEEH Voice to UltraVox

## UltraVox :

UltraVox is a voice orchestration platform that allows you to connect and manage multiple text-to-speech providers through a unified interface. Using Custom Voices, UltraVox can call external TTS APIs such as **FASEEH** and use those voices seamlessly inside UltraVox workflows.

## Prerequisites

Before starting, make sure you have:

* An active **FASEEH** account
* An active UltraVox account

## Step-by-step: Add a FASEEH Custom Voice in UltraVox

*(Detailed Video available below)*

### Step 1: Create an API Key in FASEEH

Log in to your FASEEH account and navigate to the API or Developer section. Create a new API key and copy it. Keep this key secure, as it will be used inside UltraVox.

### Step 2: Copy the Voice ID from FASEEH

In FASEEH, go to the Voices section. Select the voice you want to use. Under the voice options, you will find buttons to copy details. Use the button that copies the Voice ID and save it for later use.

### Step 3: Log in to UltraVox

Log in to your UltraVox dashboard.

### Step 4: Go to Voices and select Custom Voice

From the UltraVox navigation, open Voices and click on Custom Voice.

### Step 5: Add a new Custom Voice

Click on Add Custom Voice to create a new voice integration.

### Step 6: Fill in Voice Name and Description

Voice Name: Best practice is to use the same name as the voice in FASEEH. This makes it easier to identify and manage later.\
Description: Add a short description such as language, dialect, gender, or intended use case.

### Step 7: Configure the Custom Voice request

Copy and paste the configuration below into UltraVox. Replace the masked API key with your own FASEEH API key, and replace the Voice ID with the one you copied from FASEEH.

Example configuration:

```json theme={null}
{
"url": "https://api.faseeh.ai/api/v1/text-to-speech/faseeh-mini-v1-preview",
"headers": {
"x-api-key": "REDACTED",
"Content-Type": "application/json"
},
"body": {
"text": "{text}",
"stability": 0.5,
"speed": 1.0,
"streaming": true,
"voice_id": "YOUR_VOICE_ID"
},
"responseSampleRate": 24000
}
```

### Request details

**Authentication**\
FASEEH requires API key authentication using the x-api-key header.

**Path parameters**\
model\_id (string, required): The model identifier used for text-to-speech generation. In this example, faseeh-v1-preview is used.

**Request body fields**

* voice\_id (string, required): The FASEEH voice ID used for synthesis
* text (string, required): The Arabic text to convert into speech
* stability (number, required): A value between 0.0 and 1.0. Higher values produce more consistent output
* speed (number, optional): A value between 0.7 and 1.2. Default is 1.0\
  streaming (boolean, required): Must be false to receive a complete WAV file response

## Video

<iframe title="YouTube video player" />


# VAPI Integration
Source: https://docs.faseeh.ai/integrations/vapi-integration

Integrate Faseeh Arabic TTS with VAPI voice assistants

# Integrating Faseeh with VAPI

This guide will help you integrate Faseeh's Arabic text-to-speech into your VAPI voice assistants, enabling natural-sounding Arabic conversations in your phone calls and voice applications.

## Overview

Integrate Faseeh's Text-to-Speech (TTS) system with VAPI Assistant for complete control over Arabic voice synthesis. Whether you need brand-specific voices, advanced audio quality, or cost optimization, custom TTS gives you the flexibility to use Faseeh's high-quality Arabic voices while maintaining real-time performance.

**In this guide, you'll learn to:**

* Set up webhook authentication between VAPI and your Faseeh TTS endpoint
* Configure your VAPI assistant to use Faseeh's custom voice provider
* Understand the URL structure and parameters
* Handle edge cases and troubleshoot common issues

<Tip>
  Custom TTS maintains VAPI's real-time performance while giving you complete
  flexibility over voice synthesis, language support, and audio quality.
</Tip>

## Prerequisites

Before you begin, make sure you have:

* A [Faseeh AI](https://app.faseeh.ai) account
* A [VAPI](https://vapi.ai) account with access to custom voice configuration
* Basic familiarity with VAPI Assistant configuration

## How Faseeh TTS Integration Works

VAPI's custom TTS system operates through a webhook pattern:

<Steps>
  <Step title="Text conversion trigger">
    During a conversation, VAPI needs to convert text to speech
  </Step>

  <Step title="Request to Faseeh endpoint">
    VAPI sends a POST request to Faseeh's TTS endpoint with text and audio
    specifications
  </Step>

  <Step title="Audio generation">
    Faseeh generates Arabic audio and returns it as raw PCM data
  </Step>

  <Step title="Real-time playback">
    VAPI streams the audio to the caller in real-time
  </Step>
</Steps>

## Authentication Setup

VAPI needs secure communication with your Faseeh TTS endpoint. Use **Custom Credentials** for authentication:

### Getting Your Credential ID

To use Faseeh TTS with VAPI, you need to create a Server Configuration in the VAPI dashboard. Follow these steps:

<Steps>
  <Step title="Create a Faseeh API Key">
    First, create an API key in your Faseeh dashboard:

    1. Navigate to the [Faseeh API Keys page](https://app.faseeh.ai/en/api-keys)
    2. Click **"Generate New API Key"** or **"Create API Key"**
    3. Give your key a descriptive name (e.g., "VAPI Integration")
    4. Copy the API key immediately - you'll need it in the next step

    <Warning>
      Your API key will only be displayed once. Make sure to copy it securely before closing the dialog.
    </Warning>
  </Step>

  <Step title="Create Server Configuration in VAPI">
    Now, create a Server Configuration in the VAPI dashboard:

    1. Go to [VAPI Custom Credentials](https://dashboard.vapi.ai/settings/integrations/custom-credential)
    2. Click **"Create New Server Configuration"** or **"Add Configuration"**
    3. Fill in the configuration details:
       * **Name**: Give it a descriptive name (e.g., "Faseeh TTS")
       * **Authentication Type**: Select **"Bearer Token"**
       * **Token**: Paste your Faseeh API key from Step 1
       * **Include Bearer**: **Disable** this toggle (turn it OFF)
       * **Header Name**: Set to **`x-api-key`**
    4. Click **"Save"** or **"Create"** to save the configuration

    <img alt="VAPI Server Configuration settings showing Bearer Token authentication with x-api-key header" />
  </Step>

  <Step title="Copy Your Credential ID">
    After creating the Server Configuration:

    1. You'll see your new configuration listed in the VAPI dashboard
    2. Find the **Credential ID** (it will be a UUID like `d4a3a362-fe82-4255-b475-f30eefe8e75c`)
    3. Copy this Credential ID - you'll use it in your assistant configuration

    <Tip>
      The Credential ID is usually displayed next to the configuration name or in a details view. You can also find it in the URL when viewing the configuration details.
    </Tip>
  </Step>
</Steps>

### Using Custom Credentials in Your Assistant

Once you have your Credential ID, use it in your assistant configuration:

<CodeBlocks>
  ```json title="Assistant Configuration with Custom Credentials" theme={null}
  {
    "voice": {
      "provider": "custom-voice",
      "server": {
        "url": "https://api.faseeh.ai/api/v1/integrations/vapi/faseeh-v1-preview/ar-najdi-male-2?similarity=0.7&speed=1.0",
        "credentialId": "d4a3a362-fe82-4255-b475-f30eefe8e75c",
        "timeoutSeconds": 30
      }
    }
  }
  ```
</CodeBlocks>

<Note>
  Replace `d4a3a362-fe82-4255-b475-f30eefe8e75c` with your actual Credential ID from the VAPI dashboard.
</Note>

## URL Structure

The Faseeh TTS endpoint URL follows this structure:

```
https://api.faseeh.ai/api/v1/integrations/vapi/{model_id}/{voice_id}?similarity={similarity}&speed={speed}
```

### URL Parameters

| Parameter    | Type   | Description                                                                                      | Example             |
| ------------ | ------ | ------------------------------------------------------------------------------------------------ | ------------------- |
| `model_id`   | string | The Faseeh model to use (e.g., `faseeh-v1-preview` or `faseeh-mini-v1-preview`)                  | `faseeh-v1-preview` |
| `voice_id`   | string | The Arabic voice identifier (e.g., `ar-najdi-male-2`, `ar-uae-female-1`)                         | `ar-najdi-male-2`   |
| `similarity` | number | Voice similarity/stability (0.0 - 1.0, typically 0.5 - 0.9)                                      | `0.7`               |
| `speed`      | number | Speech speed multiplier (0.7 - 1.2, default 1.0). Values below 1.0 slow down, above 1.0 speed up | `1.0`               |

### Example URLs

```json theme={null}
// Full model with Najdi male voice
"url": "https://api.faseeh.ai/api/v1/integrations/vapi/faseeh-v1-preview/ar-najdi-male-2?similarity=0.7&speed=1.0"

// Mini model with UAE female voice
"url": "https://api.faseeh.ai/api/v1/integrations/vapi/faseeh-mini-v1-preview/ar-uae-female-1?similarity=0.8&speed=1.0"

// Full model with Hijazi male voice (slower speech)
"url": "https://api.faseeh.ai/api/v1/integrations/vapi/faseeh-v1-preview/ar-hijazi-male-1?similarity=0.75&speed=0.9"
```

## Complete Assistant Configuration

Here's a complete example of configuring your VAPI assistant with Faseeh TTS:

<CodeBlocks>
  ```json title="Complete Assistant Configuration" theme={null}
  {
    "name": "Faseeh Assistant 2",
    "voice": {
      "provider": "custom-voice",
      "server": {
        "url": "https://api.faseeh.ai/api/v1/integrations/vapi/faseeh-v1-preview/ar-najdi-male-2?similarity=0.7&speed=1.0",
        "credentialId": "d4a3a362-fe82-4255-b475-f30eefe8e75c",
        "timeoutSeconds": 30
      },
      "fallbackPlan": {
        "voices": [
          {
            "provider": "eleven-labs",
            "voiceId": "21m00Tcm4TlvDq8ikWAM"
          }
        ]
      }
    }
  }
  ```
</CodeBlocks>

## Request and Response Formats

### VAPI Request Structure

Every TTS request from VAPI follows this format:

<CodeBlocks>
  ```json title="VAPI TTS Request" theme={null}
  {
    "message": {
      "type": "voice-request",
      "text": "مرحباً، كيف يمكنني مساعدتك اليوم؟",
      "sampleRate": 24000,
      "timestamp": 1677123456789,
      "call": {
        "id": "call-123",
        "orgId": "org-456"
      },
      "assistant": {
        "id": "assistant-789",
        "name": "Faseeh Assistant"
      },
      "customer": {
        "number": "+1234567890"
      }
    }
  }
  ```
</CodeBlocks>

### Required Fields

| Field        | Type   | Description                                                |
| ------------ | ------ | ---------------------------------------------------------- |
| `type`       | string | Always "voice-request"                                     |
| `text`       | string | Text to synthesize (supports Arabic and mixed content)     |
| `sampleRate` | number | Target audio sample rate (8000, 16000, 22050, or 24000 Hz) |
| `timestamp`  | number | Unix timestamp in milliseconds                             |

### Response Format

Faseeh's endpoint automatically returns:

* **HTTP 200 status**
* **Content-Type: application/octet-stream**
* **Raw PCM audio data** in the response body

<CodeBlocks>
  ```http title="Correct Response Headers" theme={null}
  HTTP/1.1 200 OK
  Content-Type: application/octet-stream
  Transfer-Encoding: chunked

  [Raw PCM audio bytes]

  ```
</CodeBlocks>

## Audio Format Requirements

Faseeh automatically generates audio with these exact specifications:

* **Format:** Raw PCM (no headers or containers)
* **Channels:** 1 (mono only)
* **Bit Depth:** 16-bit signed integer
* **Byte Order:** Little-endian
* **Sample Rate:** Matches the `sampleRate` in the request

<Warning>
  Faseeh handles all audio format requirements automatically. No additional configuration needed.
</Warning>

## Choosing Your Voice

### Available Voice IDs

To choose a voice for your assistant:

1. Visit the [Faseeh Voice Library](https://app.faseeh.ai/en/voices)
2. Listen to different voices to find the one that best fits your use case
3. Note the voice ID (e.g., `ar-najdi-male-2`, `ar-uae-female-1`)
4. Use that voice ID in your URL

### Model Selection

Choose between two models based on your needs:

```json theme={null}
// Full model - Best quality, slightly higher latency
"url": "https://api.faseeh.ai/api/v1/integrations/vapi/faseeh-v1-preview/{voice_id}?similarity={similarity}&speed={speed}"

// Mini model - Faster, lower latency, good quality
"url": "https://api.faseeh.ai/api/v1/integrations/vapi/faseeh-mini-v1-preview/{voice_id}?similarity={similarity}&speed={speed}"
```

### Similarity Parameter

The `similarity` parameter controls voice consistency:

* **0.0 - 0.4**: More expressive, creative, but can vary more
* **0.5 - 0.7**: Balanced (recommended for most use cases)
* **0.8 - 1.0**: Very consistent, less variation

```json theme={null}
// Dynamic voice - More expressive
"url": ".../{voice_id}?similarity=0.4&speed=1.0"

// Consistent voice - Professional applications
"url": ".../{voice_id}?similarity=0.9&speed=1.0"
```

### Speed Parameter

The `speed` parameter controls speech rate:

* **0.7 - 0.9**: Slower speech (clearer for complex content)
* **1.0**: Normal speed (default)
* **1.1 - 1.2**: Faster speech (for quick responses)

```json theme={null}
// Slower speech - For clear enunciation
"url": ".../{voice_id}?similarity=0.7&speed=0.8"

// Faster speech - For rapid delivery
"url": ".../{voice_id}?similarity=0.7&speed=1.2"
```

## Testing Your Integration

### Create a Test Call

Use VAPI's API to create a test call that exercises your Faseeh TTS system:

<CodeBlocks>
  ```javascript title="Test Call Creation" theme={null}
  async function testFaseehWithVAPICall() {
    const vapiApiKey = 'your-vapi-api-key';
    const assistantId = 'your-assistant-id'; // Assistant with Faseeh TTS

    const callData = {
      assistant: { id: assistantId },
      phoneNumberId: 'your-phone-number-id',
      customer: { number: '+1234567890' }, // Your test number
    };

    try {
      const response = await fetch('https://api.vapi.ai/call', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${vapiApiKey}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(callData),
      });

      const call = await response.json();
      console.log('Test call created:', call.id);
      return call;
    } catch (error) {
      console.error('Failed to create test call:', error);
    }
  }
  ```
</CodeBlocks>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Request timeouts">
    **Symptoms:** VAPI doesn't receive your audio response, calls may drop

    **Common causes:**

    * Network connectivity issues between VAPI and Faseeh API
    * TTS processing takes longer than configured timeout
    * Server overload

    **Solutions:**

    * Increase `timeoutSeconds` in your assistant configuration (default: 30)
    * Use `faseeh-mini-v1-preview` for faster processing
    * Check your network connection and Faseeh API status
  </Accordion>

  <Accordion title="Audio playback problems">
    **Symptoms:** No audio during calls, or distorted/garbled sound

    **Common causes:**

    * Incorrect URL format or parameters
    * Invalid voice ID
    * Authentication issues

    **Solutions:**

    * Verify the URL structure matches: `/vapi/{model_id}/{voice_id}?similarity={similarity}`
    * Check that the voice ID exists in Faseeh's voice library
    * Ensure your credential ID is correct and contains a valid Faseeh API key
  </Accordion>

  <Accordion title="Authentication failures">
    **Symptoms:** 401 Unauthorized responses

    **Common causes:**

    * Invalid Faseeh API key in custom credentials
    * Missing or incorrect credential ID
    * API key expired or revoked

    **Solutions:**

    * Verify your Faseeh API key is valid at [app.faseeh.ai](https://app.faseeh.ai)
    * Check that the credential ID matches your VAPI dashboard configuration
    * Regenerate your API key if needed
  </Accordion>

  <Accordion title="High latency">
    **Symptoms:** Noticeable delays during conversations

    **Common causes:**

    * Using full model instead of mini model
    * Network latency between services
    * High similarity values requiring more processing

    **Solutions:**

    * Switch to `faseeh-mini-v1-preview` for lower latency
    * Reduce similarity value (e.g., from 0.9 to 0.7)
    * Consider geographic proximity of services
  </Accordion>

  <Accordion title="Invalid voice ID">
    **Symptoms:** 404 Not Found or invalid voice errors

    **Common causes:**

    * Typo in voice ID
    * Voice ID doesn't exist
    * Wrong model/voice combination

    **Solutions:**

    * Visit [Faseeh Voice Library](https://app.faseeh.ai/en/voices) to verify voice IDs
    * Ensure voice ID matches exactly (case-sensitive)
    * Check that the voice is available for your selected model
  </Accordion>
</AccordionGroup>

## Best Practices

### 1. API Key Security

✅ **DO:**

* Store API keys in VAPI Custom Credentials (not in code)
* Use different credentials for development and production
* Rotate keys periodically

❌ **DON'T:**

* Hardcode API keys in assistant configuration
* Share API keys in chat or email
* Use the same key across multiple environments

### 2. Similarity Settings

* **Customer Service**: 0.7 - 0.8 (balanced and reliable)
* **Professional Applications**: 0.8 - 0.9 (very consistent)
* **Creative Content**: 0.5 - 0.6 (more expressive)

### 3. Fallback Configuration

Always configure a fallback voice provider to ensure call continuity:

```json theme={null}
{
  "voice": {
    "provider": "custom-voice",
    "server": {
      "url": "https://api.faseeh.ai/api/v1/integrations/vapi/...",
      "credentialId": "...",
      "timeoutSeconds": 30
    },
    "fallbackPlan": {
      "voices": [
        {
          "provider": "eleven-labs",
          "voiceId": "21m00Tcm4TlvDq8ikWAM"
        }
      ]
    }
  }
}
```

## Next Steps

Now that you have Faseeh TTS integration working:

* **Explore Voices**: Try different Arabic voices from the [Voice Library](https://app.faseeh.ai/en/voices)
* **Optimize Performance**: Test both full and mini models to find the right balance
* **Multi-language Support**: Combine Faseeh for Arabic with other providers for English
* **Monitor Usage**: Track your API usage in the [Faseeh Dashboard](https://app.faseeh.ai)

<Tip>
  Consider implementing a fallback voice provider in your assistant configuration to ensure call continuity if your Faseeh TTS endpoint experiences issues.
</Tip>

## Support

Need help?

* **Faseeh Support**: [Schedule a Meeting](https://www.actualize.pro/schedule)
* **VAPI Support**: [VAPI Documentation](https://docs.vapi.ai)
* **Voice Library**: [Browse Available Voices](https://app.faseeh.ai/en/voices)


# Models
Source: https://docs.faseeh.ai/models

Explore Faseeh's voice synthesis models

Faseeh offers state-of-the-art Arabic voice synthesis models designed to handle various dialects and use cases.

## Meet the Models

<CardGroup>
  <Card title="Faseeh v1 Preview">
    High-quality Arabic voice synthesis model

    <div>
      <div>
        * Natural-sounding Arabic speech
      </div>

      <div>
        * Multiple Arabic dialects supported
      </div>

      <div>
        * High-quality voice generation
      </div>

      <div>
        * Optimized for clarity and naturalness
      </div>
    </div>
  </Card>

  <Card title="Faseeh v1 Mini Preview">
    Fast Arabic voice synthesis model

    <div>
      <div>
        * Low-latency generation
      </div>

      <div>
        * Multiple Arabic dialects supported
      </div>

      <div>
        * Faster model with optimized performance
      </div>

      <div>
        * Ideal for real-time applications
      </div>
    </div>
  </Card>
</CardGroup>

## Model Comparison

| Feature      | Faseeh v1 Preview        | Faseeh v1 Mini Preview   |
| ------------ | ------------------------ | ------------------------ |
| **Quality**  | High                     | High                     |
| **Speed**    | Standard                 | Fast                     |
| **Latency**  | Standard                 | Low                      |
| **Use Case** | General purpose          | Real-time applications   |
| **Dialects** | Multiple Arabic dialects | Multiple Arabic dialects |

<Note>
  **Model Selection**: Choose Faseeh v1 Preview for general use cases requiring high quality, or Faseeh v1 Mini Preview for applications requiring low latency and faster generation.
</Note>


# Audio Streaming Output
Source: https://docs.faseeh.ai/text-to-speech/audio-streaming-output



The Faseeh API supports streaming audio output for real-time text-to-speech generation. When `streaming: true` is set in your request, the API returns audio data in chunks as it's generated.

## Audio Format

Streaming responses return raw PCM audio data:

* **Format**: PCM (Pulse Code Modulation)
* **Sample Rate**: 24000 Hz
* **Channels**: Mono
* **Bit Depth**: 16-bit

## How It Works

When streaming is enabled:

1. The API starts generating audio immediately
2. Audio chunks are sent as they become available
3. You can begin playback before generation completes
4. Lower latency compared to non-streaming requests

## Example

```bash theme={null}
curl -X POST "https://api.faseeh.ai/api/v1/text-to-speech/faseeh-v1-preview" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_id": "ar-najdi-male-2",
    "text": "مرحبا بك في فصيح",
    "streaming": true,
    "stability": 0.5,
    "speed": 1
  }' \
  --output audio.pcm
```

## Handling Streaming Responses

Process the streaming PCM data in your application:

* Save chunks to a buffer
* Play audio chunks as they arrive
* Convert PCM to your desired format (WAV, MP3, etc.) if needed


# Get Started
Source: https://docs.faseeh.ai/text-to-speech/get-started



## What is Faseeh TTS?

Faseeh Text-to-Speech (TTS) is an advanced AI-powered service that converts text into high-quality audio with exceptional performance characteristics. Built specifically for the Middle East and North Africa (MENA) region, Faseeh TTS delivers natural-sounding Arabic speech with very low latency and support for multiple Arabic dialects.

### Key Features

* **Ultra-Low Latency**: Experience very good latency performance, making Faseeh TTS ideal for real-time applications and conversational AI
* **Exceptional Arabic Dialects**: Optimized for authentic Arabic speech across multiple dialects from Abu Dhabi to Rabat
* **MENA-Optimized**: Specifically designed and optimized for the Middle East and North Africa region, ensuring cultural and linguistic accuracy
* **High-Quality Audio**: Generate natural-sounding speech that captures the nuances of Arabic pronunciation and intonation

Faseeh TTS transforms your text into lifelike audio, enabling you to build voice-enabled applications, interactive systems, and content that speaks naturally in Arabic.


# Voices
Source: https://docs.faseeh.ai/text-to-speech/voices



Faseeh offers a variety of voices with different accents, including Emirati, Saudi, Qatari, Egyptian, and more.

### Example

```bash theme={null}
curl -X POST "https://api.faseeh.ai/api/v1/text-to-speech/faseeh-v1-preview" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_id": "ar-najdi-male-2",
    "text": "مرحبا بك في فصيح كيف يمكنني مساعدتك اليوم",
    "stability": 0.5,
    "speed": 1.0,
    "streaming": true
  }' \
  --output audio.pcm
```

> **Note:** This example uses the `faseeh-v1-preview` model with `ar-najdi-male-2` voice ID.

### Voices List

Below are the Featured Faseeh Voices available in our text-to-speech API.

|   Name  |   Sample  |  Dialect |     Language     |
| :-----: | :-------: | :------: | :--------------: |
|  Fahad  | <audio /> |   Najdi  | Arabic - English |
|   Lama  | <audio /> |  Hijazi  | Arabic - English |
|  James  | <audio /> | American | English - Arabic |
|   Jake  | <audio /> | American | Arabic - English |
| Mansour | <audio /> |  Emirati | Arabic - English |
|   Maha  | <audio /> |   Najdi  | Arabic - English |
|  Faisal | <audio /> |   Najdi  | English - Arabic |
|  Turki  | <audio /> |   Najdi  | Arabic - English |
|   Reem  | <audio /> |   Najdi  | Arabic - English |
| Mishari | <audio /> |   Najdi  | Arabic - English |
|   Hala  | <audio /> |   Najdi  | Arabic - English |
|   May   | <audio /> |  British | English - Arabic |
|  Latifa | <audio /> |  Emirati | Arabic - English |
|  Mishal | <audio /> |   Najdi  | Arabic - English |
|   Maya  | <audio /> | American | English - Arabic |

> **Explore all voices:** [View Complete Voice Library](https://app.faseeh.ai/en/voices)