Getting Started

Authentication

Copy page

All API requests to SM-AI-MODELS must be authenticated using an API key. This ensures only authorized clients can access the Text-to-Speech and Speech Recognition services.

On-Premise Deployments: If your instance is deployed within a private network without authentication enabled, you may skip API key headers. Check with your system administrator.

API Key

Include your API key in the X-API-Key header of every request:

Code
 
X-API-Key: YOUR_API_KEY

Alternatively, you can use the Authorization header with a Bearer token:

Code
 
Authorization: Bearer YOUR_API_KEY

Obtaining Your API Key

Contact your Unicode account manager or system administrator to receive your API credentials. Each API key is scoped to your organization and may include:

• Rate limit tier — Determines requests per minute
• Service access — TTS only, ASR only, or both
• Voice access — Which voices are available to your key

Rate Limits

Each API key has rate limits to ensure fair usage:

Limit	Default	Description
RPM	60	Requests per minute
TPM	50,000	Tokens per minute
TPD	1,000,000	Tokens per day
Concurrent	5	Maximum concurrent connections

Rate limit headers are included in API responses:

Code
 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1700000000

When rate limited, the API returns:

Code
 
{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Please retry after the reset time."
  }
}

Using the API Key

cURL

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

Python

Code
 
import os
import requests

API_KEY = os.environ.get("SM_AI_API_KEY")

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api-tts.withsm.ai/v1/audio/speech",
    headers=headers,
    json={"input": "مرحباً بكم", "voice": "Yara"}
)

Node.js

Code
 
const API_KEY = process.env.SM_AI_API_KEY;

const response = await fetch('https://api-tts.withsm.ai/v1/audio/speech', {
  method: 'POST',
  headers: {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ input: 'مرحباً بكم', voice: 'Yara' })
});

Environment Variables

Never hardcode API keys in your source code. Use environment variables:

Code
 
# .env file
SM_AI_API_KEY=your_api_key_here
SM_TTS_HOST=https://api-tts.withsm.ai
SM_ASR_HOST=https://api-asr.withsm.ai

Code
 
# Python — using python-dotenv
from dotenv import load_dotenv
import os

load_dotenv()
API_KEY = os.environ["SM_AI_API_KEY"]
TTS_HOST = os.environ.get("SM_TTS_HOST", "https://api-tts.withsm.ai")
ASR_HOST = os.environ.get("SM_ASR_HOST", "https://api-asr.withsm.ai")

Code
 
// Node.js — using dotenv
require('dotenv').config();

const API_KEY = process.env.SM_AI_API_KEY;
const TTS_HOST = process.env.SM_TTS_HOST || 'https://api-tts.withsm.ai';
const ASR_HOST = process.env.SM_ASR_HOST || 'https://api-asr.withsm.ai';

Security Best Practices

Practice	Description
Never commit keys	Add .env to .gitignore
Rotate regularly	Rotate API keys every 90 days
Use server-side only	Never expose keys in frontend/browser code
Scope access	Request minimum required permissions
Monitor usage	Review API usage logs for anomalies
Use HTTPS	Always use TLS in production

Security Headers

The API returns the following security headers on all responses:

Header	Value	Purpose
X-Content-Type-Options	nosniff	Prevents MIME-type sniffing
X-Frame-Options	DENY	Prevents clickjacking
X-XSS-Protection	1; mode=block	Enables XSS filter
Strict-Transport-Security	max-age=31536000; includeSubDomains	Enforces HTTPS
Referrer-Policy	strict-origin-when-cross-origin	Controls referrer information
Permissions-Policy	microphone=(), camera=()	Restricts browser permissions

WebSocket Authentication

For WebSocket connections, send the API key as the first message after connecting:

Code
 
{"x-api-key": "YOUR_API_KEY"}

Python example:

Code
 
import asyncio
import websockets
import json

async def authenticated_ws():
    uri = "wss://api-tts.withsm.ai/v1/audio/stream"
    async with websockets.connect(uri) as ws:
        # Send API key as first message
        await ws.send(json.dumps({"x-api-key": "YOUR_API_KEY"}))

        # Now send synthesis requests
        await ws.send(json.dumps({"text": "مرحباً", "voice": "Yara"}))

JavaScript example:

Code
 
const ws = new WebSocket('wss://api-tts.withsm.ai/v1/audio/stream');

ws.onopen = () => {
  // Send API key as first message
  ws.send(JSON.stringify({ 'x-api-key': 'YOUR_API_KEY' }));

  // Then send synthesis request
  ws.send(JSON.stringify({ text: 'مرحباً', voice: 'Yara' }));
};

Authentication Errors

Status	Error Code	Description
401	unauthorized	Missing or invalid API key
403	forbidden	API key lacks permission for this resource
403	voice_not_allowed	API key does not have access to requested voice

Code
 
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key. Include your key in the Authorization header.",
    "request_id": "req_abc123"
  }
}

Transport Security (TLS)

All API connections use TLS encryption. SM-AI-MODELS enforces TLS 1.3 as the minimum protocol version.

Protocol	TLS Requirement
REST / WebSocket	HTTPS / WSS (TLS 1.3+)
gRPC	TLS 1.3+ via ssl_channel_credentials()

Python (gRPC):

Code
 
credentials = grpc.ssl_channel_credentials()
channel = grpc.secure_channel('api-tts.withsm.ai:443', credentials)

Custom certificates (self-signed or private CA):

Code
 
with open('ca.crt', 'rb') as f:
    root_cert = f.read()
credentials = grpc.ssl_channel_credentials(root_certificates=root_cert)
channel = grpc.secure_channel('api-tts.withsm.ai:443', credentials)

On-Premise: For deployments using private CAs, pass your CA certificate to the client. See your administrator for certificate details.

---

gRPC Authentication

For gRPC connections, pass the API key as metadata using the x-api-key header:

Code
 
import grpc

metadata = [('x-api-key', API_KEY)]
channel = grpc.secure_channel('api-tts.withsm.ai:443', grpc.ssl_channel_credentials())

# Include metadata in every RPC call
response = stub.Synthesize(request, metadata=metadata)

Alternatively, use the authorization header with Bearer token:

Code
 
metadata = [('authorization', f'Bearer {API_KEY}')]

Code
 
const grpc = require('@grpc/grpc-js');

const metadata = new grpc.Metadata();
metadata.add('x-api-key', API_KEY);

client.synthesize(request, metadata, (err, response) => {
  // handle response
});