Documentation

cURL & grpcurl Examples

Copy page

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 http://localhost:9999/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "مرحباً بكم في يونيكود سولوشنز"}' \
  --output speech.mp3

All Parameters with Custom Speed

Code
 
curl -X POST http://localhost:9999/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{
    "input": "مرحباً، كيف حالك اليوم؟",
    "voice": "Nouf",
    "response_format": "wav",
    "speed": 1.5
  }' \
  --output custom.wav

Different Voices Comparison

Code
 
# Yara (Default Arabic voice)
curl -X POST http://localhost:9999/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "صباح الخير", "voice": "Yara"}' \
  -o yara.mp3

# Nouf (Alternative Arabic voice)
curl -X POST http://localhost:9999/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "صباح الخير", "voice": "Nouf"}' \
  -o nouf.mp3

# Yara_en (English voice)
curl -X POST http://localhost:9999/v1/audio/speech \
  -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 http://localhost:9999/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "مرحباً", "response_format": "mp3"}' \
  -o audio.mp3

# WAV (uncompressed, best for editing)
curl -X POST http://localhost:9999/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "مرحباً", "response_format": "wav"}' \
  -o audio.wav

# Opus (streaming optimized)
curl -X POST http://localhost:9999/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "مرحباً", "response_format": "opus"}' \
  -o audio.opus

# FLAC (lossless compression)
curl -X POST http://localhost:9999/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "مرحباً", "response_format": "flac"}' \
  -o audio.flac

Speed Variations

Code
 
# Very slow (0.25x)
curl -X POST http://localhost:9999/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "السرعة البطيئة جداً", "speed": 0.25}' \
  -o very_slow.mp3

# Slow (0.75x)
curl -X POST http://localhost:9999/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "السرعة البطيئة", "speed": 0.75}' \
  -o slow.mp3

# Normal (1.0x - default)
curl -X POST http://localhost:9999/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "السرعة العادية", "speed": 1.0}' \
  -o normal.mp3

# Fast (1.5x)
curl -X POST http://localhost:9999/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "السرعة السريعة", "speed": 1.5}' \
  -o fast.mp3

# Very fast (2.0x)
curl -X POST http://localhost:9999/v1/audio/speech \
  -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 http://localhost:9999/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "مرحباً"}' \
  -o output.mp3 \
  -v

# Save response headers to file
curl -X POST http://localhost:9999/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "مرحباً"}' \
  -o output.mp3 \
  -D headers.txt

# Show HTTP status code
curl -X POST http://localhost:9999/v1/audio/speech \
  -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 http://localhost:9999/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "test", "voice": "InvalidVoice"}' \
  -w "\nStatus: %{http_code}\n"

# Missing input (should return 400)
curl -X POST http://localhost:9999/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"voice": "Yara"}' \
  -w "\nStatus: %{http_code}\n"

# Invalid speed (should return 400)
curl -X POST http://localhost:9999/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "test", "speed": 5.0}' \
  -w "\nStatus: %{http_code}\n"

---

Speech Recognition

Basic Transcription

Code
 
curl -X POST http://localhost:8088/v1/audio/transcriptions \
  -F "file=@recording.wav"

Different Audio Formats

Code
 
# WAV format
curl -X POST http://localhost:8088/v1/audio/transcriptions \
  -F "file=@audio.wav"

# MP3 format
curl -X POST http://localhost:8088/v1/audio/transcriptions \
  -F "file=@audio.mp3"

# FLAC format (recommended for quality)
curl -X POST http://localhost:8088/v1/audio/transcriptions \
  -F "file=@audio.flac"

# OGG format
curl -X POST http://localhost:8088/v1/audio/transcriptions \
  -F "file=@audio.ogg"

# WebM format (web recordings)
curl -X POST http://localhost:8088/v1/audio/transcriptions \
  -F "file=@recording.webm"

Save Response to File

Code
 
curl -X POST http://localhost:8088/v1/audio/transcriptions \
  -F "file=@recording.wav" \
  -o transcription.json

# Pretty print JSON response
curl -X POST http://localhost:8088/v1/audio/transcriptions \
  -F "file=@recording.wav" | jq '.'

Extract Text Only

Code
 
# Using jq to extract text field
curl -X POST http://localhost:8088/v1/audio/transcriptions \
  -F "file=@recording.wav" | jq -r '.text'

# Or with grep
curl -X POST http://localhost:8088/v1/audio/transcriptions \
  -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 http://localhost:8088/v1/audio/transcriptions \
    -F "file=@$file" \
    -o "${file%.wav}.json"
done

Verbose Transcription with Timing

Code
 
curl -X POST http://localhost:8088/v1/audio/transcriptions \
  -F "file=@recording.wav" \
  -w "\nTime: %{time_total}s\nSize: %{size_upload} bytes\n"

---

Health Checks

Basic Health Check

Code
 
# TTS service
curl http://localhost:9999/health

# ASR service
curl http://localhost:8088/health

# Pretty print
curl http://localhost:9999/health | jq '.'

Expected response:

Code
 
{"status": "healthy"}

Health Check with Status Code

Code
 
# Exit with error if unhealthy
curl -f http://localhost:9999/health || echo "Service unhealthy"

# Show status code
curl -s -o /dev/null -w "%{http_code}" http://localhost:9999/health

Monitoring Script

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

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

# TTS Health
tts_status=$(curl -s http://localhost:9999/health | jq -r '.status')
echo "TTS: $tts_status"

# ASR Health
asr_status=$(curl -s http://localhost:8088/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 (port 50051)
grpcurl -plaintext localhost:50051 list

# ASR service (port 50052)
grpcurl -plaintext localhost:50052 list

Health Checks

Standard gRPC Health Check

Code
 
# TTS health check
grpcurl -plaintext -d '{"service": ""}' \
  localhost:50051 grpc.health.v1.Health/Check

# ASR health check
grpcurl -plaintext -d '{"service": ""}' \
  localhost:50052 grpc.health.v1.Health/Check

Expected response:

Code
 
{
  "status": "SERVING"
}

Watch Health Status

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

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

Describe Services

Code
 
# Describe TTS service methods
grpcurl -plaintext localhost:50051 describe

# Describe specific service
grpcurl -plaintext localhost:50051 describe sm.tts.v2.TextToSpeech

Advanced grpcurl Options

With Metadata (Headers)

Code
 
grpcurl -plaintext \
  -H "authorization: Bearer YOUR_TOKEN" \
  -d '{"service": ""}' \
  localhost:50051 grpc.health.v1.Health/Check

With Timeout

Code
 
grpcurl -plaintext \
  -max-time 5 \
  -d '{"service": ""}' \
  localhost:50051 grpc.health.v1.Health/Check

Verbose Output

Code
 
grpcurl -plaintext -v \
  -d '{"service": ""}' \
  localhost:50051 grpc.health.v1.Health/Check

Save to File

Code
 
grpcurl -plaintext \
  -d '{"service": ""}' \
  localhost:50051 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 http://localhost:9999/v1/audio/speech \
  -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 http://localhost:9999/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "مرحباً"}' \
  -o speech.mp3

Pipeline TTS to ASR

Code
 
# Generate speech and immediately transcribe it
curl -X POST http://localhost:9999/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "مرحباً بكم", "voice": "Yara"}' \
  -o temp.mp3 && \
curl -X POST http://localhost:8088/v1/audio/transcriptions \
  -F "file=@temp.mp3"

Progress Bar

Code
 
# Show upload/download progress
curl -X POST http://localhost:9999/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "مرحباً"}' \
  -o speech.mp3 \
  --progress-bar

Silent Mode (Scripts)

Code
 
# No progress, only errors
curl -sS -X POST http://localhost:9999/v1/audio/speech \
  -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 http://localhost:9999/health > /dev/null; then
  echo "✓ TTS REST API is up"
else
  echo "✗ TTS REST API is down"
fi

if grpcurl -plaintext localhost:50051 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 http://localhost:8088/health > /dev/null; then
  echo "✓ ASR REST API is up"
else
  echo "✗ ASR REST API is down"
fi

if grpcurl -plaintext localhost:50052 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 http://localhost:9999/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "مرحباً"}' \
  -o /dev/null -s

# Detailed timing
curl -X POST http://localhost:9999/v1/audio/speech \
  -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 http://localhost:9999/v1/audio/speech \
    -H "Content-Type: application/json" \
    -d "{\"input\": \"Test $i\"}" \
    -o "output_$i.mp3" &
done
wait
echo "All requests completed"

---

Tips & Best Practices

1. Always use --output or -o when downloading audio files
2. Use -f or --fail in scripts to exit on HTTP errors
3. Add -s or --silent in scripts to suppress progress
4. Use jq for parsing JSON responses
5. Set timeouts for production environments
6. Implement retry logic for network issues
7. Check health endpoints before making requests
8. 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