aiola

aiOla Python SDK

The official Python SDK for the aiOla API, designed to work seamlessly in both synchronous and asynchronous environments.

Installation

Basic Installation

pip install aiola
# or
uv add aiola

With Microphone Support

For microphone streaming functionality, install with the mic extra:

pip install 'aiola[mic]'
# or
uv add 'aiola[mic]'

Usage

Authentication

The aiOla SDK uses a two-step authentication process:

• Generate Access Token: Use your API key to create a temporary access token, save it for later use
• Create Client: Use the access token to instantiate the client

Step 1: Generate Access Token

from aiola import AiolaClient

result = AiolaClient.grant_token(
    api_key='your-api-key'
)

access_token = result['accessToken'] 
session_id = result['sessionId']

Step 2: Create Client

client = AiolaClient(
    access_token=access_token
)

Complete Example

import os
from aiola import AiolaClient

def example():
    try:
        # Step 1: Generate access token
        result = AiolaClient.grant_token(
            api_key=os.getenv('AIOLA_API_KEY')
        )
        
        # Step 2: Create client
        client = AiolaClient(
            access_token=result['accessToken']
        )
        
        # Step 3: Use client for API calls
        with open('path/to/your/audio.wav', 'rb') as audio_file:
            transcript = client.stt.transcribe_file(
                file=audio_file,
                language='en'
            )
        
        print('Transcript:', transcript)
        
    except Exception as error:
        print('Error:', error)

Session Management

Close Session:

# Terminates the session
result = AiolaClient.close_session(access_token)
print(f"Session closed at: {result['deletedAt']}")

Custom base URL (enterprises)

result = AiolaClient.grant_token(
    api_key='your-api-key',
    auth_base_url='https://mycompany.auth.aiola.ai'
)

client = AiolaClient(
    access_token=result['accessToken'],
    base_url='https://mycompany.api.aiola.ai'
)

Speech-to-Text – transcribe file

import os
from aiola import AiolaClient

def transcribe_file():
    try:
        # Step 1: Generate access token
        result = AiolaClient.grant_token(
            api_key=os.getenv('AIOLA_API_KEY')
        )
        
        # Step 2: Create client
        client = AiolaClient(
            access_token=result['accessToken']
        )
        
        # Step 3: Transcribe file
        with open('path/to/your/audio.wav', 'rb') as audio_file:
            transcript = client.stt.transcribe_file(
                file=audio_file,
                language="en"
            )

        print(transcript)
    except Exception as error:
        print('Error transcribing file:', error)

Speech-to-Text – live streaming

import os
import time
from aiola import AiolaClient, MicrophoneStream # pip install 'aiola[mic]'
from aiola.types import LiveEvents


def live_streaming():
    try:
        result = AiolaClient.grant_token(
            api_key=os.getenv("AIOLA_API_KEY") or "YOUR_API_KEY"
        )
        client = AiolaClient(access_token=result["accessToken"])
        connection = client.stt.stream(lang_code="en")

        @connection.on(LiveEvents.Transcript)
        def on_transcript(data):
            print("Transcript:", data.get("transcript", data))

        @connection.on(LiveEvents.Connect)
        def on_connect():
            print("Connected to streaming service")

        @connection.on(LiveEvents.Disconnect)
        def on_disconnect():
            print("Disconnected from streaming service")

        @connection.on(LiveEvents.Error)
        def on_error(error):
            print("Streaming error:", error)

        connection.connect()

        with MicrophoneStream(channels=1, samplerate=16000, blocksize=4096) as mic:
            mic.stream_to(connection)
            # Keep the main thread alive
            while True:
                time.sleep(0.1)

    except KeyboardInterrupt:
        print("Keyboard interrupt")
    except Exception as error:
        print("Error:", error)
    finally:
        connection.disconnect()

Text-to-Speech

import os
from aiola import AiolaClient

def create_file():
    try:
        result = AiolaClient.grant_token(
            api_key=os.getenv('AIOLA_API_KEY')
        )

        client = AiolaClient(
            access_token=result['accessToken']
        )
        
        audio = client.tts.synthesize(
            text='Hello, how can I help you today?',
            voice='jess',
            language='en'
        )

        with open('./audio.wav', 'wb') as f:
            for chunk in audio:
                f.write(chunk)
        
        print('Audio file created successfully')
    except Exception as error:
        print('Error creating audio file:', error)

create_file()

Text-to-Speech – streaming

import os
from aiola import AiolaClient

def stream_tts():
    try:
        result = AiolaClient.grant_token(
            api_key=os.getenv('AIOLA_API_KEY')
        )
        
        client = AiolaClient(
            access_token=result['accessToken']
        )
        
        stream = client.tts.stream(
            text='Hello, how can I help you today?',
            voice='jess',
            language='en'
        )

        audio_chunks = []
        for chunk in stream:
            audio_chunks.append(chunk)
        
        print('Audio chunks received:', len(audio_chunks))
    except Exception as error:
        print('Error streaming TTS:', error)

Async Client

For asynchronous operations, use the AsyncAiolaClient:

Async Speech-to-Text – file transcription

import asyncio
import os
from aiola import AsyncAiolaClient

async def transcribe_file():
    try:
        result = await AsyncAiolaClient.grant_token(
            api_key=os.getenv('AIOLA_API_KEY')
        )
        
        client = AsyncAiolaClient(
            access_token=result['accessToken']
        )
        
        with open('path/to/your/audio.wav', 'rb') as audio_file:
            transcript = await client.stt.transcribe_file(
                file=audio_file,
                language="en"
            )

        print(transcript)
    except Exception as error:
        print('Error transcribing file:', error)

if __name__ == "__main__":
    asyncio.run(transcribe_file())

Async Text-to-Speech

import asyncio
import os
from aiola import AsyncAiolaClient

async def create_audio_file():
    try:
        result = await AsyncAiolaClient.grant_token(
            api_key=os.getenv('AIOLA_API_KEY')
        )
        
        client = AsyncAiolaClient(
            access_token=result['accessToken']
        )
        
        audio = client.tts.synthesize(
            text='Hello, how can I help you today?',
            voice='jess',
            language='en'
        )

        with open('./audio.wav', 'wb') as f:
            async for chunk in audio:
                f.write(chunk)
        
        print('Audio file created successfully')
    except Exception as error:
        print('Error creating audio file:', error)

if __name__ == "__main__":
    asyncio.run(create_audio_file())

Async Text-to-Speech – streaming

import asyncio
import os
from aiola import AsyncAiolaClient

async def stream_tts():
    try:
        result = await AsyncAiolaClient.grant_token(
            api_key=os.getenv('AIOLA_API_KEY')
        )
        
        client = AsyncAiolaClient(
            access_token=result['accessToken']
        )
        
        stream = client.tts.stream(
            text='Hello, how can I help you today?',
            voice='jess',
            language='en'
        )

        audio_chunks = []
        async for chunk in stream:
            audio_chunks.append(chunk)
        
        print('Audio chunks received:', len(audio_chunks))
    except Exception as error:
        print('Error streaming TTS:', error)

if __name__ == "__main__":
    asyncio.run(stream_tts())

Requirements

• Python 3.10+
• For microphone streaming functionality: Install with pip install 'aiola[mic]'

Examples

The SDK includes several example scripts in the examples/ directory.