Voice Clone - Faseeh Documentation

Voice Clone

curl --request POST \
  --url https://api.faseeh.ai/api/v1/voices/clone \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-api-key: <api-key>' \
  --form voice_file='@example-file' \
  --form reference_audio_file='@example-file' \
  --form 'text=<string>' \
  --form stability=0.5 \
  --form 'name=<string>' \
  --form 'model=<string>' \
  --form 'description=<string>' \
  --form 'gender=<string>' \
  --form 'age=<string>' \
  --form 'languages=<string>' \
  --form 'dialects=<string>' \
  --form 'avatar_url=<string>'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "voice_id": "<string>",
  "name": "<string>",
  "languages": [
    "<string>"
  ],
  "dialect": [
    "<string>"
  ],
  "sample_url": "<string>",
  "stability": 123,
  "description": "<string>",
  "gender": "<string>",
  "age": "<string>",
  "type": "<string>",
  "avatar_url": "<string>"
}

POST

voices

clone

Voice Clone

curl --request POST \
  --url https://api.faseeh.ai/api/v1/voices/clone \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-api-key: <api-key>' \
  --form voice_file='@example-file' \
  --form reference_audio_file='@example-file' \
  --form 'text=<string>' \
  --form stability=0.5 \
  --form 'name=<string>' \
  --form 'model=<string>' \
  --form 'description=<string>' \
  --form 'gender=<string>' \
  --form 'age=<string>' \
  --form 'languages=<string>' \
  --form 'dialects=<string>' \
  --form 'avatar_url=<string>'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "voice_id": "<string>",
  "name": "<string>",
  "languages": [
    "<string>"
  ],
  "dialect": [
    "<string>"
  ],
  "sample_url": "<string>",
  "stability": 123,
  "description": "<string>",
  "gender": "<string>",
  "age": "<string>",
  "type": "<string>",
  "avatar_url": "<string>"
}

Important: Before using this endpoint, you must first generate a voice preview using the Voice Preview API. Use the preview audio file as voice_file and the original audio file as reference_audio_file when cloning the voice.

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

{
  "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

{
  "errorCode": "400xx",
  "errorMessage": "voice_file is required and must be a file"
}

{
  "errorCode": "400xx",
  "errorMessage": "reference_audio_file is required and must be a file"
}

{
  "errorCode": "400xx",
  "errorMessage": "name is required"
}

{
  "errorCode": "400xx",
  "errorMessage": "text is required"
}

{
  "errorCode": "400xx",
  "errorMessage": "stability must be a number between 0 and 1"
}

{
  "errorCode": "400xx",
  "errorMessage": "model is required"
}

401 Unauthorized

{
  "errorCode": "40101",
  "errorMessage": "Invalid or missing API key"
}

500 Internal Server Error

{
  "errorCode": "50001",
  "errorMessage": "Failed to process voice file"
}

{
  "errorCode": "50001",
  "errorMessage": "Failed to upload voice file"
}

Example Usage

JavaScript

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

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

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"

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.

Authorizations

x-api-key

string

header

required

API key for authentication

Body

multipart/form-data

voice_file

file

required

The generated preview audio file from the preview API

reference_audio_file

file

required

The original audio file used for the preview

text

string

required

The text used in preview generation

stability

number

required

Voice stability (0.0 to 1.0). Higher values produce more consistent output

Required range: 0 <= x <= 1

name

string

required

Name for the cloned voice

model

string

required

Model identifier to use for voice cloning

description

string

Description of the voice

gender

string

Gender of the voice (e.g., 'male', 'female')

age

string

Age category of the voice (e.g., 'middle', 'elderly')

languages

string

Comma-separated list of language codes (e.g., 'ar,en')

dialects

string

Comma-separated list of dialects (e.g., 'najdi,hijazi')

avatar_url

string

URL to an avatar image for the voice (you can put your image URL here)

Response

Voice created successfully

string<uuid>

required

Unique identifier for the voice record

voice_id

string

required

Voice identifier used in API calls

name

string

required

Name of the cloned voice

languages

string[]

required

List of language codes supported by the voice

dialect

string[]

required

List of dialects supported by the voice

sample_url

string<uri>

required

URL to the sample audio file

stability

number

required

Voice stability value

description

string | null

Description of the voice

gender

string | null

Gender of the voice

age

string | null

Age category of the voice

type

string | null

Voice type

avatar_url

string<uri> | null

URL to the avatar image

Voice Preview

Denoise

Documentation Index

​Authentication

​Request

​Form Data

​Notes

​Response

​Response Schema

​Example Response

​Error Responses

​Example Usage

​JavaScript

​Python

​cURL

Authorizations

Body

Response

Authentication

Request

Form Data

Notes

Response

Response Schema

Example Response

Error Responses

Example Usage

JavaScript

Python

cURL