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 Authorization header of every request:

Code
 
Authorization: Bearer YOUR_API_KEY

Alternatively, you can use the X-API-Key header:

Code
 
X-API-Key: YOUR_API_KEY

Obtaining Your API Key

Contact your Unicode Solutions 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

Using the API Key

cURL

Code
 
curl -X POST http://YOUR_HOST:9999/v1/audio/speech \
  -H "Authorization: Bearer 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 = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(
    "http://YOUR_HOST:9999/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('http://YOUR_HOST:9999/v1/audio/speech', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${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=http://localhost:9999
SM_ASR_HOST=http://localhost:8088

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", "http://localhost:9999")
ASR_HOST = os.environ.get("SM_ASR_HOST", "http://localhost:8088")

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 || 'http://localhost:9999';
const ASR_HOST = process.env.SM_ASR_HOST || 'http://localhost:8088';

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

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"
  }
}

gRPC Authentication

For gRPC connections, pass the API key as metadata:

Code
 
import grpc

metadata = [('authorization', f'Bearer {API_KEY}')]
channel = grpc.insecure_channel('YOUR_HOST:50051')

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

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

const metadata = new grpc.Metadata();
metadata.add('authorization', `Bearer ${API_KEY}`);

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