Documentation

REST API Reference

Copy page

SM-AI-MODELS REST API provides simple HTTP endpoints for Text-to-Speech and Speech Recognition.

Base URL: https://api.withsm.ai — single gateway for all services. TTS routes are namespaced under /v1/tts/..., ASR routes under /v1/asr/.... All requests require X-API-Key (see Authentication). For streaming: See Streaming API for WebSocket and gRPC

---

Text-to-Speech (TTS)

Convert text to natural-sounding speech with our neural TTS engine.

Endpoint

Code
 
POST https://api.withsm.ai/v1/tts/audio/speech

Service: SM-TTS-V1

Request Body

Parameter	Type	Required	Default	Description
input	string	Yes	—	Text to synthesize (see limits for maximum length)
voice	string	No	Yara	Voice name. One of: Yara, Nouf, Atheer, Yara_en
response_format	string	No	mp3	Audio format. One of: mp3, wav, opus, flac, pcm, aac
speed	number	No	1.0	Speech speed (0.5 to 2.0)

Available Voices

Voice	Language	Description
Yara	Arabic	Female voice — Natural and clear
Nouf	Arabic	Female voice — Warm and expressive
Atheer	Arabic	Female voice — Soft, conversational
Yara_en	English	Female voice — Professional

Audio Formats

Format	Content-Type	Use Case
mp3	audio/mpeg	Web playback, small file size
wav	audio/wav	High quality, editing
opus	audio/opus	Streaming, low latency
flac	audio/flac	Lossless compression
pcm	audio/pcm	Raw PCM samples — best for piping into another encoder
aac	audio/aac	Mobile/HLS-friendly compressed audio

Examples

Basic Arabic TTS

Code
 
curl -X POST https://api.withsm.ai/v1/tts/audio/speech \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "مرحباً بكم في يونيكود"}' \
  --output speech.mp3

English with Custom Speed

Code
 
curl -X POST https://api.withsm.ai/v1/tts/audio/speech \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Welcome to Unicode",
    "voice": "Yara_en",
    "speed": 1.2
  }' \
  --output english.mp3

WAV Format Output

Code
 
curl -X POST https://api.withsm.ai/v1/tts/audio/speech \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Testing WAV format",
    "voice": "Nouf",
    "response_format": "wav"
  }' \
  --output audio.wav

Response

On success, returns binary audio data with the appropriate Content-Type header.

Error Response

Code
 
{
  "error": "http_error",
  "detail": "Text cannot be empty",
  "code": "HTTP_400"
}

See Error Handling for the full error-response reference.

Handling Long Text

For text exceeding the maximum length, split it into smaller chunks:

Code
 
def split_text(text, max_length=5000):
    """Split long text into manageable chunks."""
    words = text.split()
    chunks = []
    current_chunk = []
    current_length = 0

    for word in words:
        word_length = len(word) + 1  # +1 for space
        if current_length + word_length > max_length:
            chunks.append(' '.join(current_chunk))
            current_chunk = [word]
            current_length = word_length
        else:
            current_chunk.append(word)
            current_length += word_length

    if current_chunk:
        chunks.append(' '.join(current_chunk))

    return chunks

# Generate speech for each chunk
long_text = "Your very long text here..."
chunks = split_text(long_text)

for i, chunk in enumerate(chunks):
    response = requests.post(
        "https://api.withsm.ai/v1/tts/audio/speech",
        headers={"X-API-Key": API_KEY},
        json={"input": chunk, "voice": "Yara"}
    )
    with open(f"part_{i}.mp3", "wb") as f:
        f.write(response.content)

Performance Tips

Audio Format Selection

Format	File Size	Quality	Best For
mp3	Smallest	Good	Web playback, storage efficiency
opus	Small	Excellent	Streaming, low-latency apps
flac	Medium	Lossless	Archiving, post-processing
wav	Largest	Lossless	Editing, highest quality

Speed Optimization

Code
 
# For fastest response, use mp3 format
response = requests.post(
    "https://api.withsm.ai/v1/tts/audio/speech",
    headers={"X-API-Key": API_KEY},
    json={
        "input": "مرحباً",
        "response_format": "mp3"  # Fastest encoding
    }
)

Concurrent Requests

Code
 
import concurrent.futures
import requests

def generate_speech(text, voice="Yara"):
    response = requests.post(
        "https://api.withsm.ai/v1/tts/audio/speech",
        headers={"X-API-Key": API_KEY},
        json={"input": text, "voice": voice}
    )
    return response.content

# Generate multiple audio files in parallel
texts = ["مرحباً", "صباح الخير", "مساء الخير"]

with concurrent.futures.ThreadPoolExecutor(max_workers=5) as executor:
    futures = [executor.submit(generate_speech, text) for text in texts]
    results = [future.result() for future in futures]

---

Speech Recognition (ASR)

Convert audio to text with our high-accuracy, multi-language speech recognition engine.

Endpoint

Code
 
POST https://api.withsm.ai/v1/asr/audio/transcriptions

Service: SM-STT-V1

Request

Send audio as multipart/form-data:

Parameter	Type	Required	Default	Description
file	file	Yes	—	Audio file to transcribe
language	string	No	auto	Language routing: ar (Arabic), en (English), or auto (auto-detect). Explicit values skip language classification (~50–100ms faster).
model	string	No	sm-asr	Model identifier. Currently ignored — automatic routing is used.
prompt	string	No	—	Optional text to guide transcription style.
response_format	string	No	json	Output format: json, text, verbose_json, srt, vtt.
temperature	float	No	—	Sampling temperature, 0–1.
timestamp_granularities[]	array of string	No	[segment]	For verbose_json only. Allowed values: segment, word.

The response includes an X-Model-ID header indicating which model handled the request (sm-ASR-1 for Arabic, sm-ASR-2 for English).

Language Support

The SM-STT-V1 engine supports Arabic and English with optional explicit routing:

Language	Support Level	language value
Arabic (MSA, Gulf, Egyptian, Levantine)	✓ Full support	ar
English	✓ Full support	en
Auto-detect	Default	auto (or omit the field)

Key features:

• Automatic language detection when language is omitted or set to auto
• Set language=ar or language=en to skip classification and shave ~50–100ms off latency
• Mixed-language content is handled by the auto-detect path

Supported Audio Formats

Format	Extension	Notes
FLAC	.flac	Recommended for quality
MP3	.mp3	Common format
WAV	.wav	Uncompressed audio
OGG	.ogg	Open format
WebM	.webm	Web recordings

Examples

Auto-detect language (default):

Code
 
curl -X POST https://api.withsm.ai/v1/asr/audio/transcriptions \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@recording.wav"

Explicit Arabic (skips classification, ~50–100ms faster):

Code
 
curl -X POST https://api.withsm.ai/v1/asr/audio/transcriptions \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@recording.wav" \
  -F "language=ar"

Verbose JSON with word-level timestamps:

Code
 
curl -X POST https://api.withsm.ai/v1/asr/audio/transcriptions \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@recording.wav" \
  -F "language=en" \
  -F "response_format=verbose_json" \
  -F "timestamp_granularities[]=word"

Response

Code
 
{
  "text": "مرحباً بكم في خدمات يونيكود",
  "model_id": "primary"
}

Best Practices

Tips for best results:

• Audio quality: Use clear audio with minimal background noise
• Sample rate: 16kHz or higher recommended for best accuracy
• Speakers: Single speaker audio works best
• Duration: Keep audio segments under 30 seconds for optimal performance
• File size: Check API Limits for maximum file size
• Format: Use FLAC for best quality-to-size ratio
• Bit depth: 16-bit minimum, higher is better

For long recordings:

Code
 
from pydub import AudioSegment

def split_audio(file_path, segment_length_ms=30000):
    """Split long audio into 30-second segments."""
    audio = AudioSegment.from_file(file_path)
    segments = []

    for i in range(0, len(audio), segment_length_ms):
        segment = audio[i:i + segment_length_ms]
        segment_path = f"segment_{i//segment_length_ms}.wav"
        segment.export(segment_path, format="wav")
        segments.append(segment_path)

    return segments

Error Response

Code
 
{
  "error": "http_error",
  "detail": "Invalid file type",
  "code": "HTTP_400"
}

See Error Handling for the full error-response reference.

---

Advanced ASR Endpoint

Transcribe with Diarization

For advanced transcription with speaker identification, use the /v1/asr/transcribe endpoint:

Code
 
POST https://api.withsm.ai/v1/asr/transcribe

Request fields (multipart/form-data):

Parameter	Type	Required	Default	Description
file	file	Yes	—	Audio file to transcribe
diarize	boolean	No	false	Enable speaker diarization (adds ~2s/min of audio).
language	string	No	auto	Language routing: ar, en, or auto. Explicit values skip classification (~50–100ms faster).

Example — Arabic meeting with diarization:

Code
 
curl -X POST https://api.withsm.ai/v1/asr/transcribe \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@meeting.wav" \
  -F "diarize=true" \
  -F "language=ar"

Response:

Code
 
{
  "segments": [
    {
      "text": "مرحباً بكم في الاجتماع",
      "speaker": "SPEAKER_00",
      "start_time": 0.0,
      "end_time": 2.5,
      "words": [
        {
          "word": "مرحباً",
          "start_time": 0.0,
          "end_time": 0.8,
          "confidence": 0.98
        }
      ]
    }
  ],
  "model_id": "sm-asr"
}

Features:

• Speaker identification and labeling
• Word-level timestamps
• Segment-level speaker attribution
• Language auto-detect by default; explicit ar/en for lower latency

Use Cases:

• Meeting transcriptions
• Multi-speaker conversations
• Call center analytics

---

Try It

Go to the API Reference to test these endpoints interactively with the API playground.

---

Next Steps

• Optimization & Limits — API limits and performance tuning
• Streaming API — WebSocket and gRPC for real-time audio
• cURL Examples — Comprehensive cURL examples
• gRPC Guide — Use gRPC APIs for high performance
• Error Handling — Handle errors properly
• Python Integration — Python code examples
• Node.js Integration — JavaScript/TypeScript examples