Voice

Overview

The Voice API lets you clone a voice from an audio sample and synthesize natural-sounding Arabic (or English) speech from any text. Generated audio can be sent to contacts as voice messages or used in any workflow that accepts an audio URL.

Voice synthesis supports all major Arabic dialects — Saudi, Egyptian, Levantine, Gulf, and more.

Each account's voice data is fully isolated — your cloned voice, settings, and generated audio are private to your account.

How it works

1. Configure your dialect and language preferences (PATCH /voice/settings)
2. Clone a voice by uploading a sample recording (POST /voice/clone)
3. Synthesize speech from any text (POST /voice/tts)

The system automatically warms up the voice before synthesis to minimize latency.

Voice settings

Get voice settings

GET /api/v1/voice

{
  "enabled": true,
  "voice_configured": true,
  "has_cloned_voice": true,
  "voice_id": "voice_abc123",
  "voice_name": "Layla - Customer Support",
  "language": "ar",
  "dialect": "ksa",
  "voice_preloaded_at": "2026-03-08T14:00:00.000000Z"
}

Check connectivity

GET /api/v1/voice/status

Tests whether the voice service is connected and ready.

{
  "configured": true,
  "connected": true
}

Update voice settings

PATCH /api/v1/voice/settings

# Enable voice with Egyptian Arabic dialect
curl -X PATCH https://dashboard.skylightchat.com/api/v1/voice/settings \
  -H "X-Api-Key: ••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{ "dialect": "egy", "language": "ar", "enabled": true }'

Supported dialects

GET /api/v1/voice/dialects

Returns all supported dialect codes:

Clone a voice

POST /api/v1/voice/clone

Upload an audio sample to create a cloned voice. The pipeline extracts a transcription from the recording, then registers a custom voice model scoped to your account.

This is a multipart/form-data request:

Tips for best results:

• Use a quiet recording with no background noise
• Minimum 10 seconds of clear speech
• WAV or MP3 at 44.1 kHz is ideal

curl -X POST https://dashboard.skylightchat.com/api/v1/voice/clone \
  -H "X-Api-Key: ••••••••••••" \
  -F "audio_file=@/path/to/sample.wav" \
  -F "name=Layla - Support Agent" \
  -F "language=ar" \
  -F "dialect=ksa" \
  -F "gender=female"

{
  "success": true,
  "data": {
    "voice_id": "voice_abc123",
    "voice_name": "Layla - Support Agent",
    "language": "ar",
    "dialect": "ksa"
  },
  "message": "Voice cloned successfully. Use POST /voice/preload to cache it for zero-latency TTS."
}

Returns 201 Created. Voice enabled is set to true automatically.

Warm up the voice

POST /api/v1/voice/preload

Pre-loads the cloned voice into the inference cache for near-zero latency on the first TTS request.

The system auto-warms the voice before synthesis if the last preload was more than 60 minutes ago. Call this endpoint before high-traffic periods to ensure immediate availability.

{
  "success": true,
  "data": {
    "voice_id": "voice_abc123",
    "preloaded_at": "2026-03-08T14:00:00.000000Z"
  }
}

Synthesize speech

POST /api/v1/voice/tts

Convert text to speech using your cloned voice. Returns a public URL to the generated audio file.

Prerequisites

• enabled: true — set via PATCH /voice/settings
• has_cloned_voice: true — clone a voice via POST /voice/clone

curl -X POST https://dashboard.skylightchat.com/api/v1/voice/tts \
  -H "X-Api-Key: ••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{ "text": "مرحباً بك في شركتنا، كيف يمكنني مساعدتك؟" }'

{
  "success": true,
  "data": {
    "audio_url": "https://dashboard.skylightchat.com/public/client/voice_samples/tts_9_abc.m4a",
    "format": "m4a",
    "text_length": 42
  }
}

The audio URL is publicly accessible. Audio is returned as M4A (AAC) for maximum compatibility with messaging platforms.

Delete voice

DELETE /api/v1/voice

Permanently deletes your cloned voice and clears all voice metadata from your account.

Returns 204 No Content.