📚 Supernal TTS API Documentation

Under Development

The Supernal TTS API is currently in active development. Some features may be incomplete, unstable, or subject to breaking changes. Please use with caution in production environments.

Base URL

https://tts.supernal.ai/api/v1

Authentication

Currently, the API is open for development. In production, add authentication headers:

Authorization: Bearer YOUR_API_KEY

Endpoints

1. Generate Audio

Generate TTS audio from text, with automatic caching.

Endpoint: POST /generate

Request Body:

{
  "text": "The text to convert to speech",
  "options": {
    "provider": "openai",      // optional: openai, cartesia, azure, mock
    "voice": "fable",          // optional: provider-specific voice
    "speed": 1.0,              // optional: 0.25 to 4.0
    "format": "mp3",           // optional: mp3, wav, ogg
    "quality": "medium",       // optional: low, medium, high
    "language": "en-US",       // optional: language code
    "cache": true,             // optional: enable caching (default: true)
    "ttl": 86400              // optional: cache TTL in seconds
  },
  "metadata": {
    "contentId": "blog-post-123",
    "userId": "user-456",
    "tags": ["blog", "tech"],
    "priority": 1
  }
}

Response:

{
  "hash": "a1b2c3d4e5f6...",
  "audioUrl": "/api/v1/audio/a1b2c3d4e5f6",
  "cached": false,
  "duration": 12.5,
  "cost": 0.0045,
  "metadata": {
    "provider": "openai",
    "voice": "fable",
    "generatedAt": "2024-01-20T10:30:00Z",
    "fileSize": 245760
  }
}

Status Codes:

200 - Success
400 - Invalid request
429 - Rate limit exceeded
500 - Server error

Example:

curl -X POST https://tts.supernal.ai/api/v1/generate \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello world!",
    "options": {
      "provider": "openai",
      "voice": "nova"
    }
  }'

2. Retrieve Audio

Get the generated audio file by hash.

Endpoint: GET /audio/{hash}

Response: Audio file (binary)

Headers:

Content-Type: audio/mpeg
Content-Length: 245760
Cache-Control: public, max-age=31536000
ETag: "a1b2c3d4e5f6"
X-Provider: openai
X-Cached-Tier: disk

Example:

curl https://tts.supernal.ai/api/v1/audio/a1b2c3d4e5f6 -o output.mp3

3. Get Audio Metadata

Retrieve metadata about a cached audio file.

Endpoint: GET /audio/{hash}/metadata

Response:

{
  "hash": "a1b2c3d4e5f6",
  "originalText": "Hello world!",
  "normalizedText": "hello world",
  "provider": "openai",
  "voice": "nova",
  "language": "en-US",
  "format": "mp3",
  "duration": 1.2,
  "fileSize": 24576,
  "sampleRate": 24000,
  "bitrate": 128000,
  "generatedAt": "2024-01-20T10:30:00Z",
  "lastAccessedAt": "2024-01-20T11:00:00Z",
  "accessCount": 5,
  "cost": {
    "amount": 0.00015,
    "currency": "USD",
    "charactersCharged": 12
  }
}

4. Check Audio Exists

Check if audio exists without downloading it.

Endpoint: HEAD /audio/{hash}

Response:

200 - Audio exists
404 - Audio not found

5. Delete Cached Audio

Remove audio from cache.

Endpoint: DELETE /cache/{hash}

Response:

{
  "deleted": true
}

6. Get Cache Statistics

Get overall cache statistics.

Endpoint: GET /cache/stats

Response:

{
  "totalEntries": 1234,
  "totalSize": 1073741824,
  "oldestEntry": "2024-01-01T00:00:00Z",
  "newestEntry": "2024-01-20T15:30:00Z"
}

7. Clear Cache

Clear all cached audio files (admin only).

Endpoint: DELETE /cache

Response:

{
  "message": "Cache cleared"
}

8. List Supported Voices

Get available voices for a provider.

Endpoint: GET /voices?provider={provider}

Query Parameters:

provider (optional) - Filter by provider

Response:

{
  "voices": [
    "alloy",
    "echo",
    "fable",
    "onyx",
    "nova",
    "shimmer"
  ]
}

9. List Supported Languages

Get supported languages for a provider.

Endpoint: GET /languages?provider={provider}

Response:

{
  "languages": [
    "en", "es", "fr", "de", "it", "pt", "ru", "zh", "ja", "ko"
  ]
}

10. Estimate Cost

Estimate the cost of generating audio without actually generating it.

Endpoint: POST /estimate

Request Body:

{
  "text": "Your text here",
  "options": {
    "provider": "openai",
    "quality": "high"
  }
}

Response:

{
  "cost": 0.0045,
  "characterCount": 150,
  "currency": "USD"
}

11. Get Available Providers

List all configured providers with their capabilities.

Endpoint: GET /providers

Response:

{
  "providers": [
    {
      "name": "openai",
      "voices": ["alloy", "echo", "fable", "onyx", "nova", "shimmer"],
      "languages": ["en", "es", "fr", "de", "it", "pt", "ru", "zh", "ja", "ko"]
    },
    {
      "name": "cartesia",
      "voices": ["barbershop-man", "broadway-diva", "confident-british-man"],
      "languages": ["en", "es", "fr", "de", "pt", "zh", "ja", "hi"]
    },
    {
      "name": "azure",
      "voices": ["en-US-JennyNeural", "en-US-GuyNeural", "en-GB-SoniaNeural"],
      "languages": ["en-US", "en-GB"]
    },
    {
      "name": "mock",
      "voices": ["mock-voice-1", "mock-voice-2", "mock-voice-3"],
      "languages": ["en", "es", "fr", "de", "it", "pt", "ru", "zh", "ja", "ko"]
    }
  ]
}

12. Get Provider Statistics

Get usage statistics for each provider.

Endpoint: GET /stats/providers

Response:

{
  "stats": {
    "openai": {
      "requests": 1523,
      "charactersProcessed": 4567890,
      "totalCost": 68.52,
      "avgLatency": 198,
      "errors": 3
    },
    "cartesia": {
      "requests": 892,
      "charactersProcessed": 2345678,
      "totalCost": 18.76,
      "avgLatency": 42,
      "errors": 1
    }
  }
}

13. Health Check

Check API health status.

Endpoint: GET /health

Response:

{
  "status": "ok",
  "service": "supernal-tts-api",
  "timestamp": "2024-01-20T10:30:00Z",
  "uptime": 3600
}

14. Readiness Check

Check if the service is ready to handle requests.

Endpoint: GET /health/ready

Response:

{
  "ready": true,
  "timestamp": "2024-01-20T10:30:00Z"
}

15. Liveness Check

Check if the service is alive.

Endpoint: GET /health/live

Response:

{
  "live": true,
  "timestamp": "2024-01-20T10:30:00Z"
}

Error Responses

All errors follow this format:

{
  "error": {
    "message": "Human-readable error message",
    "code": "ERROR_CODE",
    "provider": "openai",
    "details": {
      // Additional error details
    }
  }
}

Error Codes

Code	Description	HTTP Status
`INVALID_VOICE`	Voice not supported by provider	400
`INVALID_SPEED`	Speed out of valid range	400
`INVALID_FORMAT`	Audio format not supported	400
`PROVIDER_NOT_CONFIGURED`	Provider not set up	500
`OPENAI_GENERATION_ERROR`	OpenAI API error	502
`CARTESIA_GENERATION_ERROR`	Cartesia API error	502
`AZURE_GENERATION_ERROR`	Azure API error	502
`RATE_LIMIT_EXCEEDED`	Too many requests	429

Rate Limiting

Default rate limits:

100 requests per minute per IP
Configurable via API_RATE_LIMIT environment variable

Rate limit headers:

RateLimit-Limit: 100
RateLimit-Remaining: 95
RateLimit-Reset: 1642680000

Provider-Specific Options

OpenAI Options

{
  "provider": "openai",
  "voice": "fable",        // alloy, echo, fable, onyx, nova, shimmer
  "quality": "high",       // standard or high (HD)
  "speed": 1.0            // 0.25 to 4.0
}

Cartesia Options

{
  "provider": "cartesia",
  "voice": "confident-british-man",
  "speed": 1.0,           // 0.5 to 2.0
  "emotion": {
    "positivity": 0.8,    // -1 to 1
    "energy": 0.6         // -1 to 1
  }
}

Azure Options

{
  "provider": "azure",
  "voice": "en-US-JennyNeural",
  "speed": 1.0,           // 0.5 to 2.0
  "pitch": 0              // -50 to 50 (semitones)
}

Mock Options

{
  "provider": "mock",
  "voice": "mock-voice-1"
}

Webhooks (Future)

Configure webhooks for async generation:

{
  "text": "Long text content...",
  "options": { "provider": "openai" },
  "webhook": {
    "url": "https://yourapp.com/tts-webhook",
    "headers": {
      "X-Auth-Token": "your-token"
    }
  }
}

Client SDKs

JavaScript/TypeScript

npm install @supernal-tts/client

import { TTSClient } from '@supernal-tts/client';

const client = new TTSClient({
  apiUrl: 'https://tts.supernal.ai'
});

const { audioUrl } = await client.generate({
  text: "Hello world!"
});

Python (Coming Soon)

from supernal_tts import TTSClient

client = TTSClient(api_url="https://tts.supernal.ai")
response = client.generate("Hello world!")

Postman Collection

Import the Postman collection for easy API testing.

OpenAPI Specification

View the OpenAPI spec for detailed schema information.

🎧 Try the API Live

Development Demo

This is a development preview using our mock provider. The actual API may behave differently and is subject to changes as we continue development.

For more examples and integration guides, see the Examples section.

Base URL​

Authentication​

Endpoints​

1. Generate Audio​

2. Retrieve Audio​

3. Get Audio Metadata​

4. Check Audio Exists​

5. Delete Cached Audio​

6. Get Cache Statistics​

7. Clear Cache​

8. List Supported Voices​

9. List Supported Languages​

10. Estimate Cost​

11. Get Available Providers​

12. Get Provider Statistics​

13. Health Check​

14. Readiness Check​

15. Liveness Check​

Error Responses​

Error Codes​

Rate Limiting​

Provider-Specific Options​

OpenAI Options​

Cartesia Options​

Azure Options​

Mock Options​

Webhooks (Future)​

Client SDKs​

JavaScript/TypeScript​

Python (Coming Soon)​

Postman Collection​

OpenAPI Specification​

🎧 Try the API Live​

Base URL

Authentication

Endpoints

1. Generate Audio

2. Retrieve Audio

3. Get Audio Metadata

4. Check Audio Exists

5. Delete Cached Audio

6. Get Cache Statistics

7. Clear Cache

8. List Supported Voices

9. List Supported Languages

10. Estimate Cost

11. Get Available Providers

12. Get Provider Statistics

13. Health Check

14. Readiness Check

15. Liveness Check

Error Responses

Error Codes

Rate Limiting

Provider-Specific Options

OpenAI Options

Cartesia Options

Azure Options

Mock Options

Webhooks (Future)

Client SDKs

JavaScript/TypeScript

Python (Coming Soon)

Postman Collection

OpenAPI Specification

🎧 Try the API Live