Skip to content

AethexAI TTS API Documentation

Welcome to the AethexAI TTS API documentation! This is the official documentation for the Aethex Text-to-Speech API with authentication and usage tracking.

Version: 0.1.0
Base URL: https://api.aethexai.com

Getting Started

To get started with the Aethex API, follow these steps:

  1. Register and authenticate
  2. Explore the API endpoints
  3. Check out the code examples

Authentication

The Aethex API uses JWT (JSON Web Tokens) for authentication. You'll need to login to receive an access token.

Login Example

import requests

# Login to get access token
login_url = "https://api.aethexai.com/auth/jwt/login"
login_data = {
    "grant_type": "password",
    "username": "your_email@example.com",
    "password": "your_password"
}

response = requests.post(login_url, data=login_data)
token_data = response.json()
access_token = token_data["access_token"]

# Use token in subsequent requests
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

API Reference

Authentication Endpoints

POST /auth/jwt/login

Authenticate and receive JWT access token.

Request Body (form-data): 

{
  "grant_type": "password",
  "username": "user@example.com",
  "password": "your_password",
  "scope": "",
  "client_id": null,
  "client_secret": null
}

Response: 

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "token_type": "bearer"
}

POST /auth/jwt/logout

Logout and invalidate current session.

POST /auth/request-verify-token

Request email verification token.

Request Body: 

{
  "email": "user@example.com"
}

POST /auth/verify

Verify email with verification token.

Request Body: 

{
  "token": "verification_token_string"
}

User Management

GET /users/me

Get current user information.

Headers: Authorization: Bearer <token>

PATCH /users/me

Update current user information.

Headers: Authorization: Bearer <token>

Organizations

GET /organizations

List organizations with role-based filtering.

Query Parameters: - limit (int): Maximum 100, default 50 - offset (int): Minimum 0, default 0
- status (string): Filter by organization status

POST /organizations

Create a new organization (SYSTEM_ADMIN only).

Request Body: 

{
  "name": "Organization Name",
  "domain": "example.com",
  "admin_email": "admin@example.com",
  "daily_word_limit": 100000,
  "monthly_word_limit": 2000000,
  "rate_limit_per_minute": 100
}

GET /organizations/{org_id}

Get organization details with role-based access.

PATCH /organizations/{org_id}

Update organization with role-based access.

Request Body: 

{
  "name": "Updated Name",
  "domain": "newdomain.com",
  "domain_verified": true,
  "status": "active",
  "daily_word_limit": 1000,
  "monthly_word_limit": 10000,
  "rate_limit_per_minute": 10,
  "settings": {}
}

GET /organizations/{org_id}/users

Get users for an organization.

GET /organizations/{org_id}/usage

Get usage statistics for an organization.

Invitations

POST /invitations

Create an invitation with role-based organization access.

Request Body: 

{
  "email": "user@example.com",
  "role": "ORG_USER",
  "organization_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

GET /invitations

List invitations with role-based filtering.

GET /invitations/{token}/accept

Show invitation acceptance page.

POST /invitations/{token}/accept

Accept an invitation and create user account.

Request Body: 

{
  "token": "invitation_token",
  "password": "new_password",
  "full_name": "John Doe"
}

Usage Tracking

GET /usage

Get usage summary with role-based access.

Query Parameters: - user_id (UUID): Target user ID (ORG_ADMIN/SYSTEM_ADMIN only)

GET /usage/requests

Get request history with role-based access.

Query Parameters: - user_id (UUID): Target user ID (ORG_ADMIN/SYSTEM_ADMIN only) - limit (int): Number of requests to return (max 100, default 50) - offset (int): Number of requests to skip (default 0) - status (string): Filter by status (pending, success, failed)

Text-to-Speech (TTS)

POST /tts/tts

Synthesize text to speech and return complete audio file.

Request Body: 

{
  "audio_format": "mp3",
  "sample_rate_hz": 24000,
  "text": "Welcome to our text-to-speech service!",
  "voice_id": "en_female_warm_1"
}

Response: Audio file data

System Health

GET /health

Health check endpoint.

Response: 

{
  "status": "healthy",
  "env": "production",
  "timestamp": "2025-09-06T15:35:15.480Z",
  "version": "0.1.0"
}

Code Examples

Complete TTS Workflow

import requests
import base64

class AethexAPI:
    def __init__(self, base_url="https://api.aethexai.com"):
        self.base_url = base_url
        self.access_token = None

    def login(self, username, password):
        """Login and store access token"""
        url = f"{self.base_url}/auth/jwt/login"
        data = {
            "grant_type": "password",
            "username": username,
            "password": password
        }

        response = requests.post(url, data=data)
        response.raise_for_status()

        token_data = response.json()
        self.access_token = token_data["access_token"]
        return token_data

    def synthesize_speech(self, text, voice_id="en_female_warm_1", audio_format="mp3"):
        """Generate speech from text"""
        if not self.access_token:
            raise ValueError("Must login first")

        url = f"{self.base_url}/tts/tts"
        headers = {
            "Authorization": f"Bearer {self.access_token}",
            "Content-Type": "application/json"
        }
        data = {
            "text": text,
            "voice_id": voice_id,
            "audio_format": audio_format,
            "sample_rate_hz": 24000
        }

        response = requests.post(url, headers=headers, json=data)
        response.raise_for_status()

        return response.content

    def get_usage(self):
        """Get current usage statistics"""
        if not self.access_token:
            raise ValueError("Must login first")

        url = f"{self.base_url}/usage"
        headers = {"Authorization": f"Bearer {self.access_token}"}

        response = requests.get(url, headers=headers)
        response.raise_for_status()

        return response.json()

# Usage example
api = AethexAPI()

# Login
api.login("your_email@example.com", "your_password")

# Generate speech
audio_data = api.synthesize_speech("Hello, welcome to AethexAI!")

# Save audio file
with open("output.mp3", "wb") as f:
    f.write(audio_data)

# Check usage
usage_stats = api.get_usage()
print(f"Current usage: {usage_stats}")

JavaScript/Node.js Example

const axios = require('axios');

class AethexAPI {
    constructor(baseURL = 'https://api.aethexai.com') {
        this.baseURL = baseURL;
        this.accessToken = null;
    }

    async login(username, password) {
        const response = await axios.post(`${this.baseURL}/auth/jwt/login`, {
            grant_type: 'password',
            username,
            password
        }, {
            headers: { 'Content-Type': 'application/x-www-form-urlencoded' }
        });

        this.accessToken = response.data.access_token;
        return response.data;
    }

    async synthesizeSpeech(text, voiceId = 'en_female_warm_1') {
        if (!this.accessToken) {
            throw new Error('Must login first');
        }

        const response = await axios.post(`${this.baseURL}/tts/tts`, {
            text,
            voice_id: voiceId,
            audio_format: 'mp3',
            sample_rate_hz: 24000
        }, {
            headers: {
                'Authorization': `Bearer ${this.accessToken}`,
                'Content-Type': 'application/json'
            },
            responseType: 'arraybuffer'
        });

        return response.data;
    }
}

Error Handling

All API responses follow standard HTTP status codes:

  • 200: Success
  • 400: Bad Request (e.g., invalid credentials)
  • 401: Unauthorized (missing or invalid token)
  • 422: Validation Error
  • 429: Rate Limit Exceeded

Error Response Format: 

{
  "detail": [
    {
      "loc": ["field_name"],
      "msg": "Error message",
      "type": "error_type"
    }
  ]
}

Rate Limiting

The API implements rate limiting per organization: - Default: 100 requests per minute - Daily word limit: Configurable per organization - Monthly word limit: Configurable per organization

When limits are exceeded, you'll receive a 429 Too Many Requests response.

Authentication Flow

  1. Login: POST /auth/jwt/login with credentials
  2. Get Token: Receive access_token in response
  3. Use Token: Include Authorization: Bearer <token> in headers
  4. Refresh: Login again when token expires

Organization Roles

  • SYSTEM_ADMIN: Full system access, can manage all organizations
  • ORG_ADMIN: Can manage their organization and users
  • ORG_USER: Standard user access within organization

Support

For support, please contact: - Email: support@aethexai.com - Documentation: This site - API Status: Check /health endpoint

Changelog

v0.1.0 - Initial API release - JWT authentication - TTS synthesis - Organization management - Usage tracking

API Documentation v0.1.0 - Last updated: September 6, 2025