API Reference

Voice

Generate natural Arabic speech with SkyLight Talk — use a built-in preset voice, or clone a custom brand voice.

Overview

The Voice API (SkyLight Talk) turns text into natural-sounding Arabic or English speech. Generated audio can be sent to contacts as voice messages or used in any workflow that accepts an audio URL.

You can work in either of two modes:

Mode	When to use	Cloning required?
Preset	Pick one of SkyLight Talk's built-in voices (Layla, Noura, Ahmed, …)	No
Clone	Upload a short sample and clone a custom brand voice	Yes (plan feature)

Voice synthesis supports major Arabic dialects — Saudi, Egyptian, Levantine, Gulf, and more. Each account's voice data is fully isolated.

Most integrations should start with preset mode. No audio upload, no cloning plan requirement — just pick a voice name and call /voice/tts.

How it works

Preset voice (no cloning)

List available voices (GET /voice/voices)
Select a voice + enable TTS (PATCH /voice/settings)
Synthesize speech (POST /voice/tts)

Cloned voice

Configure dialect / language (PATCH /voice/settings)
Clone from a sample recording (POST /voice/clone)
Synthesize speech (POST /voice/tts)

Voice settings

Get voice settings

GET /api/v1/voice

{
  "enabled": true,
  "voice_configured": true,
  "mode": "preset",
  "tts_ready": true,
  "has_cloned_voice": false,
  "voice_id": null,
  "voice_name": null,
  "language": "ar",
  "dialect": "ksa",
  "preset_voice": "Layla",
  "preset_language": "ar-SA",
  "preset_style_prompt": null,
  "voice_cloning_enabled": true,
  "voice_minutes_limit": 800,
  "voice_minutes_remaining": 742.5
}

Field	Description
`mode`	Active mode: `preset` or `clone`
`tts_ready`	Whether synthesis can run right now
`enabled`	Whether voice auto-responds to your contacts
`preset_voice`	Selected built-in voice brand name (preset mode)
`has_cloned_voice`	Whether a custom cloned voice is ready (clone mode)
`voice_cloning_enabled`	Whether your plan allows cloning

Check connectivity

GET /api/v1/voice/status

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

Update voice settings

PATCH /api/v1/voice/settings

Field	Type	Notes
`mode`	string	`preset` or `clone`
`enabled`	boolean	Enable/disable voice synthesis for your account
`preset_voice`	string	Brand voice name from `GET /voice/voices` (e.g. `Layla`)
`preset_language`	string	BCP-47 accent code or `auto` (see languages in `/voice/voices`)
`preset_style_prompt`	string	Optional speaking-style instructions (tone, pace, persona)
`language`	string	`ar` or `en` (clone mode)
`dialect`	string	Dialect code from `GET /voice/dialects` (clone mode)

# Switch to a built-in voice — no cloning needed
curl -X PATCH https://dashboard.skylightchat.com/api/v1/voice/settings \
  -H "X-Api-Key: ••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "preset",
    "preset_voice": "Layla",
    "preset_language": "ar-SA",
    "enabled": true
  }'

Selecting preset_voice automatically switches you to preset mode and enables TTS if enabled is omitted.

Built-in preset voices

GET /api/v1/voice/voices

Returns all SkyLight Talk built-in voices (brand names only), plus supported language / accent codes. Use the name value exactly as shown when calling PATCH /voice/settings.

Female voices

Name	Style
`Noura`	Bright
`Layla`	Firm
`Sarah`	Youthful
`Maryam`	Breezy
`Fatima`	Easy-going
`Aisha`	Bright
`Huda`	Smooth
`Yasmin`	Clear
`Reem`	Upbeat
`Salma`	Soft
`Khadija`	Mature
`Zainab`	Forward
`Nada`	Gentle
`Amal`	Warm

Male voices

Name	Style
`Ahmed`	Upbeat
`Mohammed`	Informative
`Omar`	Excitable
`Ali`	Firm
`Youssef`	Breathy
`Khaled`	Clear
`Tariq`	Easy-going
`Hassan`	Smooth
`Hussein`	Gravelly
`Mahmoud`	Informative
`Abdullah`	Firm
`Ibrahim`	Even
`Majed`	Friendly
`Waleed`	Casual
`Sami`	Lively
`Yasser`	Knowledgeable

{
  "mode": "preset",
  "voices": [
    {
      "name": "Layla",
      "gender": "female",
      "tags": ["Firm"],
      "languages": ["ar-XA", "ar-SA", "en-US"]
    },
    {
      "name": "Ahmed",
      "gender": "male",
      "tags": ["Upbeat"],
      "languages": ["ar-XA", "ar-SA", "en-US"]
    }
  ],
  "languages": {
    "arabic": [
      { "code": "ar-SA", "label": "Saudi Arabic (Gulf)" },
      { "code": "ar-EG", "label": "Egyptian Arabic" }
    ]
  }
}

The tables above list every current preset voice. Prefer GET /voice/voices at runtime so your integration stays in sync if new voices are added.

Supported dialects (clone mode)

GET /api/v1/voice/dialects

Code	Dialect
`arb`	Modern Standard Arabic (MSA)
`ksa`	Saudi / Khaleeji
`egy`	Egyptian
`leb`	Lebanese
`syr`	Syrian
`jor`	Jordanian
`irq`	Iraqi
`uae`	Emirati
`bah`	Bahraini
`qat`	Qatari
`pls`	Palestinian
`msa`	Formal Modern Standard Arabic
`en`	English

Clone a voice

POST /api/v1/voice/clone

Upload an audio sample to create a custom cloned voice. Requires voice_cloning_enabled on your plan.

This endpoint may take 30–90 seconds. Use a generous request timeout.

multipart/form-data fields:

Field	Type	Required	Notes
`audio_file`	file	✓	mp3, wav, ogg, m4a, webm, mp4, aac, flac — max 32 MB
`name`	string	✓	Display name for the voice
`language`	string	No	`ar` or `en` (default: `ar`)
`dialect`	string	No	Dialect code (default: `arb`)
`gender`	string	No	`male` or `female` (default: `female`)
`style`	string	No	`conversational` or `narrator` (default: `conversational`)

Tips for best results:

Quiet recording, no background noise
At least 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",
    "mode": "clone"
  },
  "message": "Voice cloned successfully. Use POST /voice/preload to cache it for zero-latency TTS."
}

Returns 201 Created. Mode is set to clone and enabled becomes true automatically.

Warm up a cloned voice

POST /api/v1/voice/preload

Pre-loads the cloned voice into the inference cache for near-zero latency on the first TTS request. Only applies to clone mode.

The system auto-warms the voice before synthesis if the last preload was more than 60 minutes ago.

{
  "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 the active mode (preset voice or cloned voice). Returns a public URL to the generated audio file.

Prerequisites

Preset mode

mode: "preset"
preset_voice set (e.g. Layla)

Clone mode

mode: "clone"
enabled: true
has_cloned_voice: true

Field	Type	Required	Notes
`text`	string	✓	1–5000 characters. Arabic fully supported.

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,
    "mode": "preset"
  }
}

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

Quick start — preset voice only

# 1. See available voices
curl https://dashboard.skylightchat.com/api/v1/voice/voices \
  -H "X-Api-Key: ••••••••••••"

# 2. Pick Layla (Saudi female) and enable TTS
curl -X PATCH https://dashboard.skylightchat.com/api/v1/voice/settings \
  -H "X-Api-Key: ••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "preset", "preset_voice": "Layla", "preset_language": "ar-SA", "enabled": true }'

# 3. Generate speech
curl -X POST https://dashboard.skylightchat.com/api/v1/voice/tts \
  -H "X-Api-Key: ••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{ "text": "أهلاً وسهلاً، كيف أقدر أخدمك اليوم؟" }'

Delete cloned voice

DELETE /api/v1/voice

Permanently deletes your cloned voice and clears clone-mode metadata. Preset voices are unaffected — switch with PATCH /voice/settings instead.

Deleting a cloned voice is irreversible. You must clone a new sample to use clone mode again.

Returns 204 No Content.

Knowledge Base

Manage the AI knowledge base that powers automated responses across your channels.

Media

Upload and manage your image and video library via the API.