> ## Documentation Index
> Fetch the complete documentation index at: https://docs.faseeh.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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


## OpenAPI

````yaml POST /voices/preview
openapi: 3.1.0
info:
  title: Faseeh API
  description: >-
    Faseeh - First True Arabic Voice AI that speaks Dialects From Abu Dhabi to
    Rabat with Voice Cloning & On-prem support
  version: 1.0.0
servers:
  - url: https://api.faseeh.ai/api/v1
    description: Production server
security:
  - apiKeyAuth: []
paths:
  /voices/preview:
    post:
      tags:
        - Voice Cloning
      summary: Voice Preview
      description: >-
        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.
      operationId: voicePreview
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - text
                - similarity
                - model_id
                - file
              properties:
                text:
                  type: string
                  description: >-
                    Text to generate preview with (minimum 3 words, 10
                    characters)
                similarity:
                  type: number
                  minimum: 0
                  maximum: 1
                  description: >-
                    Voice similarity to source (0.0 to 1.0). Higher values
                    produce more similar voice
                model_id:
                  type: string
                  description: The model identifier to use for generation
                speed:
                  type: number
                  minimum: 0.7
                  maximum: 1.2
                  default: 1
                  description: Speech speed (0.7 to 1.2, default 1.0)
                file:
                  type: string
                  format: binary
                  description: Audio file containing the voice to preview
      responses:
        '200':
          description: Streaming PCM16 audio preview
          content:
            audio/raw:
              schema:
                type: string
                format: binary
                description: PCM16 audio stream (24000 Hz, Mono, 16-bit)
          headers:
            Content-Type:
              schema:
                type: string
                example: audio/raw;codec=pcm16;rate=24000;channels=1
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Payment Required - Insufficient wallet balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error - Failed to generate voice preview
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      required:
        - errorCode
        - errorMessage
      properties:
        errorCode:
          type: string
          description: Error code identifier
        errorMessage:
          type: string
          description: Human-readable error message
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication

````