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


## OpenAPI

````yaml POST /voices/clone
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/clone:
    post:
      tags:
        - Voice Cloning
      summary: Voice Clone
      description: >-
        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.
      operationId: cloneVoice
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - voice_file
                - reference_audio_file
                - text
                - stability
                - name
                - model
              properties:
                voice_file:
                  type: string
                  format: binary
                  description: The generated preview audio file from the preview API
                reference_audio_file:
                  type: string
                  format: binary
                  description: The original audio file used for the preview
                text:
                  type: string
                  description: The text used in preview generation
                stability:
                  type: number
                  minimum: 0
                  maximum: 1
                  description: >-
                    Voice stability (0.0 to 1.0). Higher values produce more
                    consistent output
                name:
                  type: string
                  description: Name for the cloned voice
                model:
                  type: string
                  description: Model identifier to use for voice cloning
                description:
                  type: string
                  description: Description of the voice
                gender:
                  type: string
                  description: Gender of the voice (e.g., 'male', 'female')
                age:
                  type: string
                  description: Age category of the voice (e.g., 'middle', 'elderly')
                languages:
                  type: string
                  description: Comma-separated list of language codes (e.g., 'ar,en')
                dialects:
                  type: string
                  description: Comma-separated list of dialects (e.g., 'najdi,hijazi')
                avatar_url:
                  type: string
                  description: >-
                    URL to an avatar image for the voice (you can put your image
                    URL here)
      responses:
        '200':
          description: Voice created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClonedVoice'
        '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'
        '500':
          description: Internal Server Error - Failed to create voice
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ClonedVoice:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the voice record
        voice_id:
          type: string
          description: Voice identifier used in API calls
        name:
          type: string
          description: Name of the cloned voice
        description:
          type: string
          nullable: true
          description: Description of the voice
        gender:
          type: string
          nullable: true
          description: Gender of the voice
        age:
          type: string
          nullable: true
          description: Age category of the voice
        languages:
          type: array
          items:
            type: string
          description: List of language codes supported by the voice
        dialect:
          type: array
          items:
            type: string
          description: List of dialects supported by the voice
        type:
          type: string
          nullable: true
          description: Voice type
        sample_url:
          type: string
          format: uri
          description: URL to the sample audio file
        avatar_url:
          type: string
          format: uri
          nullable: true
          description: URL to the avatar image
        stability:
          type: number
          description: Voice stability value
      required:
        - id
        - voice_id
        - name
        - languages
        - dialect
        - sample_url
        - stability
    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

````