API Reference

Complete API reference for Supernal TTS

📚 Supernal TTS API Documentation

:::caution 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. Generate Audio (Progressive Streaming)

Generate audio with progressive streaming using Server-Sent Events (SSE). Ideal for long-form content.

Endpoint: POST /generate-progressive

Request Body: Same as /generate

Response: Server-Sent Events stream

Event Types:

// Started event
{
  "type": "started",
  "totalChunks": 5
}

// Progress events
{
  "type": "progress",
  "completed": 3,
  "total": 5,
  "progress": 60
}

// Complete event
{
  "type": "complete",
  "hash": "a1b2c3d4e5f6...",
  "audioUrl": "/api/v1/audio/a1b2c3d4e5f6",
  "duration": 12.5,
  "chunks": 5,
  "parallelTime": 2.3,
  "metadata": {
    "provider": "openai",
    "voice": "fable",
    "generatedAt": "2024-01-20T10:30:00Z",
    "fileSize": 245760
  }
}

// Error event
{
  "type": "error",
  "message": "Error description"
}

Example:

const eventSource = new EventSource('/api/v1/generate-progressive', {
  method: 'POST',
  body: JSON.stringify({
    text: "Your long text here...",
    options: { provider: "openai", voice: "nova" }
  })
});

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'progress') {
    console.log(`Progress: ${data.progress}%`);
  } else if (data.type === 'complete') {
    console.log('Audio ready:', data.audioUrl);
    eventSource.close();
  }
};

3. 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
Accept-Ranges: bytes

Example:

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

4. Get Audio Metadata

Retrieve metadata about a cached audio file without downloading it.

Endpoint: GET /audio/{hash}/metadata

Response:

{
  "hash": "a1b2c3d4e5f6",
  "provider": "openai",
  "voice": "nova",
  "language": "en-US",
  "format": "mp3",
  "duration": 1.2,
  "fileSize": 24576,
  "generatedAt": "2024-01-20T10:30:00Z",
  "lastAccessedAt": "2024-01-20T11:00:00Z",
  "accessCount": 5
}

5. Check Audio Exists

Check if audio exists without downloading it (HEAD request).

Endpoint: HEAD /audio/{hash}

Response:

200 - Audio exists (with Content-Length header)
404 - Audio not found

Example:

curl -I https://tts.supernal.ai/api/v1/audio/a1b2c3d4e5f6

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

7. Get Available Providers

List all configured providers.

Endpoint: GET /providers

Response:

{
  "providers": ["openai", "mock"]
}

8. List Supported Voices

Get available voices for a provider.

Endpoint: GET /voices?provider={provider}

Query Parameters:

provider (optional) - Filter by provider (e.g., "openai")

Response:

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

9. Get Hash Information

Get all hash variants (direct, content, semantic) for given text and options.

Endpoint: POST /hash-info

Request Body:

{
  "text": "Your text here",
  "options": {
    "provider": "openai",
    "voice": "nova"
  }
}

Response:

{
  "hashes": {
    "direct": "a1b2c3d4e5f6...",
    "content": "x7y8z9...",
    "semantic": "m3n4o5..."
  },
  "text": {
    "original": "Your text here",
    "length": 15
  }
}

10. Lookup Cached Audio by Hash

Lookup cached audio using different hash modes with optional fallback.

Endpoint: POST /hash-lookup

Request Body:

{
  "text": "Your text here",
  "options": {
    "provider": "openai",
    "voice": "nova"
  },
  "hashMode": "semantic",      // "direct", "content", or "semantic"
  "allowFallback": true         // optional: try other hash modes if not found
}

Response (found):

{
  "found": true,
  "hash": "a1b2c3d4e5f6...",
  "mode": "semantic",
  "confidence": 0.95,
  "audioUrl": "/api/v1/audio/a1b2c3d4e5f6",
  "metadata": {
    "provider": "openai",
    "voice": "nova",
    "duration": 1.2,
    "fileSize": 24576,
    "generatedAt": "2024-01-20T10:30:00Z"
  }
}

Response (not found):

{
  "found": false,
  "hashes": {
    "direct": "a1b2c3...",
    "content": "x7y8z9...",
    "semantic": "m3n4o5..."
  },
  "message": "No cached audio found for this content"
}

11. Check if Content Exists

Quick check if content exists in cache without retrieving it.

Endpoint: POST /hash-exists

Request Body:

{
  "text": "Your text here",
  "options": {
    "provider": "openai",
    "voice": "nova"
  },
  "hashMode": "direct"  // "direct", "content", or "semantic"
}

Response:

{
  "exists": true,
  "hashMode": "direct",
  "hashes": {
    "direct": "a1b2c3d4e5f6...",
    "content": "x7y8z9...",
    "semantic": "m3n4o5..."
  }
}

12. Delete Cached Audio (Admin)

Remove audio from cache. Requires admin authentication.

Endpoint: DELETE /cache/{hash}

Headers:

Authorization: Bearer ADMIN_API_KEY

Response:

{
  "deleted": true
}

13. Get Cache Statistics (Admin)

Get overall cache statistics. Requires admin authentication.

Endpoint: GET /cache/stats

Headers:

Authorization: Bearer ADMIN_API_KEY

Response:

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

14. Clear Cache (Admin)

Clear all cached audio files. Requires admin authentication.

Endpoint: DELETE /cache

Headers:

Authorization: Bearer ADMIN_API_KEY

Response:

{
  "message": "Cache cleared successfully"
}

15. Health Check

Check API health status.

Endpoint: GET /health

Response:

{
  "status": "healthy",
  "timestamp": "2024-01-20T10:30:00Z",
  "uptime": 3600,
  "environment": "production",
  "version": "0.1.0"
}

Upcoming Features

The following endpoints are planned but not yet implemented:

GET /languages?provider={provider} - List supported languages by provider
GET /stats/providers - Get usage statistics for each provider
GET /health/ready - Kubernetes readiness probe
GET /health/live - Kubernetes liveness probe

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": "coral",        // alloy, echo, fable, onyx, nova, shimmer, coral
  "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"
}

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.

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