Python SDK

Python SDK Documentation

Official Python SDK for the OrbitalsAI API with sync and async support. Build powerful African language transcription into your Python applications.

Python 3.8+
Stable
PyPI Package

Installation

Install the SDK using pip:

bash
bash
pip install orbitalsai

Authentication

Get your API key from the dashboard and initialize the client:

main.py
python
import orbitalsai
client = orbitalsai.Client(api_key="your_api_key_here")
Best Practice
Store your API key as an environment variable to keep it secure.

Basic Usage

Transcribe an audio file with automatic waiting:

main.py
python
import orbitalsai
client = orbitalsai.Client(api_key="your_api_key_here")
# Transcribe with automatic waiting
transcript = client.transcribe("audio.mp3", model_name="Perigee-1")
print(transcript.text)
print(transcript.audio_duration)  # Duration in seconds
Automatic Waiting
The transcribe() method automatically waits for the transcription to complete before returning.

Specify a Language

Transcribe with a specific African language:

main.py
python
# Transcribe in Hausa
transcript = client.transcribe(
    "audio.mp3",
    language="hausa"
)
# Transcribe in Igbo
transcript = client.transcribe(
    "audio.mp3",
    language="igbo"
)

See the full list of supported languages.

Model Selection

Choose the best AI model for your needs. You can list available models and their pricing:

main.py
python
# List available models
models = client.get_models()
for model in models:
    print(f"{model.model_name}: $\{model.transcription_rate_per_hour}/hr")
# Transcribe using a specific model
transcript = client.transcribe(
    "audio.mp3",
    model_name="Perigee-1"  # Default model
)

Generate SRT Subtitles

Generate subtitle files in SRT format:

main.py
python
transcript = client.transcribe(
    "audio.mp3",
    language="yoruba",
    generate_srt=True
)
print(transcript.text)
print(transcript.srt_content)  # SRT subtitle content
# Save to file
with open("subtitles.srt", "w", encoding="utf-8") as f:
    f.write(transcript.srt_content)

Async Usage

Use the async client for non-blocking operations:

main.py
python
import asyncio
import orbitalsai
async def transcribe_audio():
    client = orbitalsai.AsyncClient(api_key="your_api_key_here")
    
    transcript = await client.transcribe("audio.mp3", language="swahili", model_name="Perigee-1")
    print(transcript.text)
asyncio.run(transcribe_audio())
Concurrent Processing
Use the async client to process multiple files concurrently for better performance.

Manual Task Control

Submit a transcription task without waiting:

main.py
python
# Submit task
task = client.submit_transcription_task(
    "audio.mp3",
    language="hausa"
)
print(f"Task ID: {task.task_id}")
print(f"Status: {task.status}")
# Check status later
task = client.get_transcription_task(task.task_id)
if task.status == "completed":
    transcript = client.get_transcript(task.task_id)
    print(transcript.text)

Error Handling

Handle common errors gracefully:

main.py
python
from orbitalsai.exceptions import (
    AuthenticationError,
    InsufficientBalanceError,
    TranscriptionError,
    TimeoutError
)
try:
    transcript = client.transcribe("audio.mp3", language="pidgin")
    print(transcript.text)
except AuthenticationError:
    print("Invalid API key")
except InsufficientBalanceError:
    print("Not enough balance. Please top up your account.")
except TranscriptionError as e:
    print(f"Transcription failed: {e}")
except TimeoutError:
    print("Transcription took too long")
except Exception as e:
    print(f"Unexpected error: {e}")

Balance Management

Check your account balance and usage:

main.py
python
# Check balance
balance = client.get_balance()
print(f"Current balance: $\{balance.balance:.2f}")
print(f"Last updated: $\{balance.last_updated}")
# Get usage history
usage = client.get_usage_history()
for record in usage:
    print(f"Date: {record.date}, Amount: $\{record.amount:.2f}")

Complete Example

A complete example with error handling and balance checking:

main.py
python
import orbitalsai
from orbitalsai.exceptions import InsufficientBalanceError, TranscriptionError
import os
def main():
    # Initialize client
    client = orbitalsai.Client(api_key=os.environ["ORBITALS_API_KEY"])
    
    # Check balance
    balance = client.get_balance()
    print(f"Current balance: $\{balance.balance:.2f}")
    
    if balance.balance < 1.0:
        print("⚠️  Low balance. Please top up.")
        return
    
    # Transcribe audio
    try:
        transcript = client.transcribe(
            "audio.mp3",
            language="hausa",
            model_name="Perigee-1",
            generate_srt=True
        )
        
        print("✅ Transcription successful!")
        print(f"Text: {transcript.text}")
        print(f"Duration: {transcript.audio_duration:.2f}s")
        print(f"Words: {transcript.word_count}")
        
        # Save transcript
        with open("transcript.txt", "w", encoding="utf-8") as f:
            f.write(transcript.text)
        
        # Save subtitles
        if transcript.srt_content:
            with open("subtitles.srt", "w", encoding="utf-8") as f:
                f.write(transcript.srt_content)
        
    except InsufficientBalanceError:
        print("❌ Insufficient balance")
    except TranscriptionError as e:
        print(f"❌ Transcription failed: {e}")
if __name__ == "__main__":
    main()