Documentation

cURL & grpcurl Examples

Complete guide to using SM-AI-MODELS with cURL (REST) and grpcurl (gRPC).

Prerequisites

Code
 
# cURL (usually pre-installed)
curl --version

# grpcurl for gRPC testing
brew install grpcurl  # macOS
# or
go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest

REST API Examples (cURL)

Text-to-Speech

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

All Parameters 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": "مرحباً، كيف حالك اليوم؟",
    "voice": "Sherine",
    "response_format": "wav",
    "speed": 1.5
  }' \
  --output custom.wav

Different Voices Comparison

Code
 
# Yara (Default Arabic voice)
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": "صباح الخير", "voice": "Yara"}' \
  -o yara.mp3

# Sherine (Egyptian dialect) — or use "dialect": "ar-egyptian"
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": "صباح الخير", "voice": "Sherine"}' \
  -o sherine.mp3

# Myriam (Levantine dialect) — or use "dialect": "ar-levantine"
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": "صباح الخير", "voice": "Myriam"}' \
  -o myriam.mp3

# Yara_en (English voice)
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": "Good morning", "voice": "Yara_en"}' \
  -o english.mp3

Multiple Formats

Code
 
# MP3 (default, smallest file)
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": "مرحباً", "response_format": "mp3"}' \
  -o audio.mp3

# WAV (uncompressed, best for editing)
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": "مرحباً", "response_format": "wav"}' \
  -o audio.wav

# Opus (streaming optimized)
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": "مرحباً", "response_format": "opus"}' \
  -o audio.opus

# FLAC (lossless compression)
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": "مرحباً", "response_format": "flac"}' \
  -o audio.flac

Speed Variations

Code
 
# Slow (0.5x)
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": "السرعة البطيئة", "speed": 0.5}' \
  -o slow.mp3

# Normal (1.0x - default)
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": "السرعة العادية", "speed": 1.0}' \
  -o normal.mp3

# Fast (1.5x)
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": "السرعة السريعة", "speed": 1.5}' \
  -o fast.mp3

# Maximum (2.0x)
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": "السرعة السريعة جداً", "speed": 2.0}' \
  -o very_fast.mp3

Error Handling with Verbose Output

Code
 
# Show full request/response headers
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": "مرحباً"}' \
  -o output.mp3 \
  -v

# Save response headers to file
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": "مرحباً"}' \
  -o output.mp3 \
  -D headers.txt

# Show HTTP status 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": "مرحباً"}' \
  -o output.mp3 \
  -w "HTTP Status: %{http_code}\n"

Handling Errors

Code
 
# Invalid voice (should return 400)
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": "test", "voice": "InvalidVoice"}' \
  -w "\nStatus: %{http_code}\n"

# Missing input (should return 400)
curl -X POST https://api.withsm.ai/v1/tts/audio/speech \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"voice": "Yara"}' \
  -w "\nStatus: %{http_code}\n"

# Invalid speed (should return 400)
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": "test", "speed": 3.0}' \
  -w "\nStatus: %{http_code}\n"

Speech Recognition

Basic Transcription

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

Different Audio Formats

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

# MP3 format
curl -X POST https://api.withsm.ai/v1/asr/audio/transcriptions \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@audio.mp3"

# FLAC format (recommended for quality)
curl -X POST https://api.withsm.ai/v1/asr/audio/transcriptions \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@audio.flac"

# OGG format
curl -X POST https://api.withsm.ai/v1/asr/audio/transcriptions \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@audio.ogg"

# WebM format (web recordings)
curl -X POST https://api.withsm.ai/v1/asr/audio/transcriptions \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@recording.webm"

Save Response to File

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

# Pretty print JSON response
curl -X POST https://api.withsm.ai/v1/asr/audio/transcriptions \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@recording.wav" | jq '.'

Extract Text Only

Code
 
# Using jq to extract text field
curl -X POST https://api.withsm.ai/v1/asr/audio/transcriptions \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@recording.wav" | jq -r '.text'

# Or with grep
curl -X POST https://api.withsm.ai/v1/asr/audio/transcriptions \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@recording.wav" | grep -o '"text":"[^"]*"' | cut -d'"' -f4

Batch Transcription

Code
 
# Process multiple files
for file in *.wav; do
  echo "Transcribing: $file"
  curl -X POST https://api.withsm.ai/v1/asr/audio/transcriptions \
    -H "X-API-Key: YOUR_API_KEY" \
    -F "file=@$file" \
    -o "${file%.wav}.json"
done

Verbose Transcription with Timing

Code
 
curl -X POST https://api.withsm.ai/v1/asr/audio/transcriptions \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@recording.wav" \
  -w "\nTime: %{time_total}s\nSize: %{size_upload} bytes\n"

Health Checks

Basic Health Check

Code
 
# TTS service
curl https://api.withsm.ai/v1/tts/health

# ASR service
curl https://api.withsm.ai/v1/asr/health

# Pretty print
curl https://api.withsm.ai/v1/tts/health | jq '.'

Expected response:


Code
 
{"status": "healthy"}

Health Check with Status Code

Code
 
# Exit with error if unhealthy
curl -f https://api.withsm.ai/v1/tts/health || echo "Service unhealthy"

# Show status code
curl -s -o /dev/null -w "%{http_code}" https://api.withsm.ai/v1/tts/health

Monitoring Script

Code
 
#!/bin/bash
# check-services.sh

echo "=== SM-AI Services Health Check ==="

# TTS Health
tts_status=$(curl -s https://api.withsm.ai/v1/tts/health | jq -r '.status')
echo "TTS: $tts_status"

# ASR Health
asr_status=$(curl -s https://api.withsm.ai/v1/asr/health | jq -r '.status')
echo "ASR: $asr_status"

gRPC API Examples (grpcurl)

Installation

Code
 
# macOS
brew install grpcurl

# Linux
wget https://github.com/fullstorydev/grpcurl/releases/download/v1.8.9/grpcurl_1.8.9_linux_x86_64.tar.gz
tar -xvf grpcurl_1.8.9_linux_x86_64.tar.gz
sudo mv grpcurl /usr/local/bin/

# Verify
grpcurl --version

List Available Services

Code
 
# TTS service
grpcurl api.withsm.ai:9102 list

# ASR service
grpcurl api.withsm.ai:9101 list

Health Checks

Standard gRPC Health Check

Code
 
# TTS health check
grpcurl -plaintext -d '{"service": ""}' \
  api.withsm.ai:9102 grpc.health.v1.Health/Check

# ASR health check
grpcurl -plaintext -d '{"service": ""}' \
  api.withsm.ai:9101 grpc.health.v1.Health/Check

Expected response:


Code
 
{
  "status": "SERVING"
}

Watch Health Status

Code
 
# Stream health status updates for TTS
grpcurl -plaintext -d '{"service": ""}' \
  api.withsm.ai:9102 grpc.health.v1.Health/Watch

# Stream health status updates for ASR
grpcurl -plaintext -d '{"service": ""}' \
  api.withsm.ai:9101 grpc.health.v1.Health/Watch

Advanced grpcurl Options

With Metadata (Headers)

Code
 
grpcurl -plaintext \
  -H "authorization: Bearer YOUR_TOKEN" \
  -d '{"service": ""}' \
  api.withsm.ai:9102 grpc.health.v1.Health/Check

With Timeout

Code
 
grpcurl -plaintext \
  -max-time 5 \
  -d '{"service": ""}' \
  api.withsm.ai:9102 grpc.health.v1.Health/Check

Verbose Output

Code
 
grpcurl -plaintext -v \
  -d '{"service": ""}' \
  api.withsm.ai:9102 grpc.health.v1.Health/Check

Save to File

Code
 
grpcurl -plaintext \
  -d '{"service": ""}' \
  api.withsm.ai:9102 grpc.health.v1.Health/Check \
  > health-response.json

Advanced cURL Techniques

Retry Logic

Code
 
# Retry up to 3 times with delay
curl --retry 3 --retry-delay 2 \
  -X POST https://api.withsm.ai/v1/tts/audio/speech \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "مرحباً"}' \
  -o speech.mp3

Timeout Configuration

Code
 
# Connection timeout: 5s, Max time: 30s
curl --connect-timeout 5 --max-time 30 \
  -X POST https://api.withsm.ai/v1/tts/audio/speech \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "مرحباً"}' \
  -o speech.mp3

Pipeline TTS to ASR

Code
 
# Generate speech and immediately transcribe it
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": "مرحباً بكم", "voice": "Yara"}' \
  -o temp.mp3 && \
curl -X POST https://api.withsm.ai/v1/asr/audio/transcriptions \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@temp.mp3"

Progress Bar

Code
 
# Show upload/download progress
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": "مرحباً"}' \
  -o speech.mp3 \
  --progress-bar

Silent Mode (Scripts)

Code
 
# No progress, only errors
curl -sS -X POST https://api.withsm.ai/v1/tts/audio/speech \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "مرحباً"}' \
  -o speech.mp3

Testing & Debugging

Check Service Availability

Code
 
#!/bin/bash
# test-connectivity.sh

echo "Testing TTS service..."
if curl -sf https://api.withsm.ai/v1/tts/health > /dev/null; then
  echo "✓ TTS REST API is up"
else
  echo "✗ TTS REST API is down"
fi

if grpcurl api.withsm.ai:9102 list > /dev/null 2>&1; then
  echo "✓ TTS gRPC API is up"
else
  echo "✗ TTS gRPC API is down"
fi

echo -e "\nTesting ASR service..."
if curl -sf https://api.withsm.ai/v1/asr/health > /dev/null; then
  echo "✓ ASR REST API is up"
else
  echo "✗ ASR REST API is down"
fi

if grpcurl api.withsm.ai:9101 list > /dev/null 2>&1; then
  echo "✓ ASR gRPC API is up"
else
  echo "✗ ASR gRPC API is down"
fi

Performance Testing

Code
 
# Measure response time
time 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": "مرحباً"}' \
  -o /dev/null -s

# Detailed timing
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": "مرحباً"}' \
  -o /dev/null -s \
  -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTotal: %{time_total}s\n"

Load Testing

Code
 
# Simple concurrent requests
for i in {1..10}; do
  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\": \"Test $i\"}" \
    -o "output_$i.mp3" &
done
wait
echo "All requests completed"

Tips & Best Practices

Always use --output or -o when downloading audio files
Use -f or --fail in scripts to exit on HTTP errors
Add -s or --silent in scripts to suppress progress
Use jq for parsing JSON responses
Set timeouts for production environments
Implement retry logic for network issues
Check health endpoints before making requests
Use grpcurl for gRPC health monitoring

Next Steps

gRPC Guide — Deep dive into gRPC API usage
Python Integration — Python client examples
Node.js Integration — JavaScript/TypeScript examples
Error Handling — Handle errors properly
API Reference — Interactive API documentation

Last modified on July 6, 2026

Node.js Integration gRPC API Guide

Documentation

cURL & grpcurl Examples

Complete guide to using SM-AI-MODELS with cURL (REST) and grpcurl (gRPC).

Prerequisites

Code
 
# cURL (usually pre-installed)
curl --version

# grpcurl for gRPC testing
brew install grpcurl  # macOS
# or
go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest

REST API Examples (cURL)

Text-to-Speech

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

All Parameters 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": "مرحباً، كيف حالك اليوم؟",
    "voice": "Sherine",
    "response_format": "wav",
    "speed": 1.5
  }' \
  --output custom.wav

Different Voices Comparison

Code
 
# Yara (Default Arabic voice)
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": "صباح الخير", "voice": "Yara"}' \
  -o yara.mp3

# Sherine (Egyptian dialect) — or use "dialect": "ar-egyptian"
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": "صباح الخير", "voice": "Sherine"}' \
  -o sherine.mp3

# Myriam (Levantine dialect) — or use "dialect": "ar-levantine"
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": "صباح الخير", "voice": "Myriam"}' \
  -o myriam.mp3

# Yara_en (English voice)
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": "Good morning", "voice": "Yara_en"}' \
  -o english.mp3

Multiple Formats

Code
 
# MP3 (default, smallest file)
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": "مرحباً", "response_format": "mp3"}' \
  -o audio.mp3

# WAV (uncompressed, best for editing)
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": "مرحباً", "response_format": "wav"}' \
  -o audio.wav

# Opus (streaming optimized)
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": "مرحباً", "response_format": "opus"}' \
  -o audio.opus

# FLAC (lossless compression)
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": "مرحباً", "response_format": "flac"}' \
  -o audio.flac

Speed Variations

Code
 
# Slow (0.5x)
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": "السرعة البطيئة", "speed": 0.5}' \
  -o slow.mp3

# Normal (1.0x - default)
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": "السرعة العادية", "speed": 1.0}' \
  -o normal.mp3

# Fast (1.5x)
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": "السرعة السريعة", "speed": 1.5}' \
  -o fast.mp3

# Maximum (2.0x)
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": "السرعة السريعة جداً", "speed": 2.0}' \
  -o very_fast.mp3

Error Handling with Verbose Output

Code
 
# Show full request/response headers
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": "مرحباً"}' \
  -o output.mp3 \
  -v

# Save response headers to file
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": "مرحباً"}' \
  -o output.mp3 \
  -D headers.txt

# Show HTTP status 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": "مرحباً"}' \
  -o output.mp3 \
  -w "HTTP Status: %{http_code}\n"

Handling Errors

Code
 
# Invalid voice (should return 400)
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": "test", "voice": "InvalidVoice"}' \
  -w "\nStatus: %{http_code}\n"

# Missing input (should return 400)
curl -X POST https://api.withsm.ai/v1/tts/audio/speech \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"voice": "Yara"}' \
  -w "\nStatus: %{http_code}\n"

# Invalid speed (should return 400)
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": "test", "speed": 3.0}' \
  -w "\nStatus: %{http_code}\n"

Speech Recognition

Basic Transcription

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

Different Audio Formats

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

# MP3 format
curl -X POST https://api.withsm.ai/v1/asr/audio/transcriptions \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@audio.mp3"

# FLAC format (recommended for quality)
curl -X POST https://api.withsm.ai/v1/asr/audio/transcriptions \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@audio.flac"

# OGG format
curl -X POST https://api.withsm.ai/v1/asr/audio/transcriptions \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@audio.ogg"

# WebM format (web recordings)
curl -X POST https://api.withsm.ai/v1/asr/audio/transcriptions \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@recording.webm"

Save Response to File

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

# Pretty print JSON response
curl -X POST https://api.withsm.ai/v1/asr/audio/transcriptions \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@recording.wav" | jq '.'

Extract Text Only

Code
 
# Using jq to extract text field
curl -X POST https://api.withsm.ai/v1/asr/audio/transcriptions \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@recording.wav" | jq -r '.text'

# Or with grep
curl -X POST https://api.withsm.ai/v1/asr/audio/transcriptions \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@recording.wav" | grep -o '"text":"[^"]*"' | cut -d'"' -f4

Batch Transcription

Code
 
# Process multiple files
for file in *.wav; do
  echo "Transcribing: $file"
  curl -X POST https://api.withsm.ai/v1/asr/audio/transcriptions \
    -H "X-API-Key: YOUR_API_KEY" \
    -F "file=@$file" \
    -o "${file%.wav}.json"
done

Verbose Transcription with Timing

Code
 
curl -X POST https://api.withsm.ai/v1/asr/audio/transcriptions \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@recording.wav" \
  -w "\nTime: %{time_total}s\nSize: %{size_upload} bytes\n"

Health Checks

Basic Health Check

Code
 
# TTS service
curl https://api.withsm.ai/v1/tts/health

# ASR service
curl https://api.withsm.ai/v1/asr/health

# Pretty print
curl https://api.withsm.ai/v1/tts/health | jq '.'

Expected response:


Code
 
{"status": "healthy"}

Health Check with Status Code

Code
 
# Exit with error if unhealthy
curl -f https://api.withsm.ai/v1/tts/health || echo "Service unhealthy"

# Show status code
curl -s -o /dev/null -w "%{http_code}" https://api.withsm.ai/v1/tts/health

Monitoring Script

Code
 
#!/bin/bash
# check-services.sh

echo "=== SM-AI Services Health Check ==="

# TTS Health
tts_status=$(curl -s https://api.withsm.ai/v1/tts/health | jq -r '.status')
echo "TTS: $tts_status"

# ASR Health
asr_status=$(curl -s https://api.withsm.ai/v1/asr/health | jq -r '.status')
echo "ASR: $asr_status"

gRPC API Examples (grpcurl)

Installation

Code
 
# macOS
brew install grpcurl

# Linux
wget https://github.com/fullstorydev/grpcurl/releases/download/v1.8.9/grpcurl_1.8.9_linux_x86_64.tar.gz
tar -xvf grpcurl_1.8.9_linux_x86_64.tar.gz
sudo mv grpcurl /usr/local/bin/

# Verify
grpcurl --version

List Available Services

Code
 
# TTS service
grpcurl api.withsm.ai:9102 list

# ASR service
grpcurl api.withsm.ai:9101 list

Health Checks

Standard gRPC Health Check

Code
 
# TTS health check
grpcurl -plaintext -d '{"service": ""}' \
  api.withsm.ai:9102 grpc.health.v1.Health/Check

# ASR health check
grpcurl -plaintext -d '{"service": ""}' \
  api.withsm.ai:9101 grpc.health.v1.Health/Check

Expected response:


Code
 
{
  "status": "SERVING"
}

Watch Health Status

Code
 
# Stream health status updates for TTS
grpcurl -plaintext -d '{"service": ""}' \
  api.withsm.ai:9102 grpc.health.v1.Health/Watch

# Stream health status updates for ASR
grpcurl -plaintext -d '{"service": ""}' \
  api.withsm.ai:9101 grpc.health.v1.Health/Watch

Advanced grpcurl Options

With Metadata (Headers)

Code
 
grpcurl -plaintext \
  -H "authorization: Bearer YOUR_TOKEN" \
  -d '{"service": ""}' \
  api.withsm.ai:9102 grpc.health.v1.Health/Check

With Timeout

Code
 
grpcurl -plaintext \
  -max-time 5 \
  -d '{"service": ""}' \
  api.withsm.ai:9102 grpc.health.v1.Health/Check

Verbose Output

Code
 
grpcurl -plaintext -v \
  -d '{"service": ""}' \
  api.withsm.ai:9102 grpc.health.v1.Health/Check

Save to File

Code
 
grpcurl -plaintext \
  -d '{"service": ""}' \
  api.withsm.ai:9102 grpc.health.v1.Health/Check \
  > health-response.json

Advanced cURL Techniques

Retry Logic

Code
 
# Retry up to 3 times with delay
curl --retry 3 --retry-delay 2 \
  -X POST https://api.withsm.ai/v1/tts/audio/speech \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "مرحباً"}' \
  -o speech.mp3

Timeout Configuration

Code
 
# Connection timeout: 5s, Max time: 30s
curl --connect-timeout 5 --max-time 30 \
  -X POST https://api.withsm.ai/v1/tts/audio/speech \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "مرحباً"}' \
  -o speech.mp3

Pipeline TTS to ASR

Code
 
# Generate speech and immediately transcribe it
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": "مرحباً بكم", "voice": "Yara"}' \
  -o temp.mp3 && \
curl -X POST https://api.withsm.ai/v1/asr/audio/transcriptions \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@temp.mp3"

Progress Bar

Code
 
# Show upload/download progress
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": "مرحباً"}' \
  -o speech.mp3 \
  --progress-bar

Silent Mode (Scripts)

Code
 
# No progress, only errors
curl -sS -X POST https://api.withsm.ai/v1/tts/audio/speech \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "مرحباً"}' \
  -o speech.mp3

Testing & Debugging

Check Service Availability

Code
 
#!/bin/bash
# test-connectivity.sh

echo "Testing TTS service..."
if curl -sf https://api.withsm.ai/v1/tts/health > /dev/null; then
  echo "✓ TTS REST API is up"
else
  echo "✗ TTS REST API is down"
fi

if grpcurl api.withsm.ai:9102 list > /dev/null 2>&1; then
  echo "✓ TTS gRPC API is up"
else
  echo "✗ TTS gRPC API is down"
fi

echo -e "\nTesting ASR service..."
if curl -sf https://api.withsm.ai/v1/asr/health > /dev/null; then
  echo "✓ ASR REST API is up"
else
  echo "✗ ASR REST API is down"
fi

if grpcurl api.withsm.ai:9101 list > /dev/null 2>&1; then
  echo "✓ ASR gRPC API is up"
else
  echo "✗ ASR gRPC API is down"
fi

Performance Testing

Code
 
# Measure response time
time 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": "مرحباً"}' \
  -o /dev/null -s

# Detailed timing
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": "مرحباً"}' \
  -o /dev/null -s \
  -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTotal: %{time_total}s\n"

Load Testing

Code
 
# Simple concurrent requests
for i in {1..10}; do
  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\": \"Test $i\"}" \
    -o "output_$i.mp3" &
done
wait
echo "All requests completed"

Tips & Best Practices

Always use --output or -o when downloading audio files
Use -f or --fail in scripts to exit on HTTP errors
Add -s or --silent in scripts to suppress progress
Use jq for parsing JSON responses
Set timeouts for production environments
Implement retry logic for network issues
Check health endpoints before making requests
Use grpcurl for gRPC health monitoring

Next Steps

gRPC Guide — Deep dive into gRPC API usage
Python Integration — Python client examples
Node.js Integration — JavaScript/TypeScript examples
Error Handling — Handle errors properly
API Reference — Interactive API documentation

Last modified on July 6, 2026

Node.js Integration gRPC API Guide