Python SDK Documentation

pip install orbitalsai

# Add streaming dependencies (WebSocket + NumPy)
pip install "orbitalsai[streaming]"
# Add audio conversion + microphone helpers
pip install "orbitalsai[audio]"
# Install everything (streaming + audio extras)
pip install "orbitalsai[all]"

import orbitalsai
client = orbitalsai.Client(api_key="your_api_key_here")

import asyncio
import orbitalsai
async def transcribe_audio() -> None:
    async with orbitalsai.AsyncClient(api_key="your_api_key_here") as client:
        transcript = await client.transcribe(
            "audio.mp3",
            language="swahili",
            model_name="Perigee-1",
        )
        print(transcript.text)
if __name__ == "__main__":
    asyncio.run(transcribe_audio())

import orbitalsai
client = orbitalsai.Client(api_key="your_api_key_here")
# Start transcription without waiting for completion
transcript = client.transcribe(
    "audio.mp3",
    language="hausa",
    model_name="Perigee-1",
    wait=False,
)
print(f"Task ID: {transcript.task_id}")
# Poll the task status
task = client.get_task(transcript.task_id)
print(f"Status: {task.status}")
# Or block until the task completes
final_transcript = client.wait_for_task(transcript.task_id)
print(final_transcript.text)

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}")

from datetime import date, timedelta
# Check current balance
balance = client.get_balance()
print(f"Current balance: $\{balance.balance:.2f}")
print(f"Last updated: {balance.last_updated}")
# Get daily usage for the last 7 days
end_date = date.today()
start_date = end_date - timedelta(days=7)
daily_usage = client.get_daily_usage(start_date=start_date, end_date=end_date)
print(f"Total cost: $\{daily_usage.total_cost:.2f}")
print(f"Total audio processed: {daily_usage.total_audio_seconds:.1f} seconds")
for record in daily_usage.daily_records:
    print(f"{record.date}: $\{record.total_cost:.4f} ({record.transcription_usage:.1f}s transcription)")

import os
from datetime import date, timedelta
import orbitalsai
from orbitalsai.exceptions import InsufficientBalanceError, TranscriptionError
def main() -> None:
    # Initialize client
    client = orbitalsai.Client(api_key=os.environ["ORBITALSAI_API_KEY"])
    # Check balance
    balance = client.get_balance()
    print(f"Current balance: $\{balance.balance:.2f}")
    if balance.balance <= 0:
        print("Low or zero balance. Please top up before transcribing.")
        return
    # Transcribe audio with SRT
    try:
        transcript = client.transcribe(
            "audio.mp3",
            language="hausa",
            model_name="Perigee-1",
            generate_srt=True,
        )
        print("Transcription successful!\n")
        print(transcript.text)
        # Save transcript
        with open("transcript.txt", "w", encoding="utf-8") as f:
            f.write(transcript.text)
        # Save subtitles if available
        if transcript.srt_content:
            with open("subtitles.srt", "w", encoding="utf-8") as f:
                f.write(transcript.srt_content)
    except InsufficientBalanceError:
        print("Insufficient balance – please top up your account.")
    except TranscriptionError as e:
        print(f"Transcription failed: {e}")
    # Print recent usage summary
    end_date = date.today()
    start_date = end_date - timedelta(days=7)
    usage = client.get_daily_usage(start_date=start_date, end_date=end_date)
    print(f"\nLast 7 days cost: $\{usage.total_cost:.2f}")
    print(f"Total audio processed: {usage.total_audio_seconds:.1f}s")
if __name__ == "__main__":
    main()

import asyncio
from orbitalsai.streaming import AsyncStreamingClient, PrintingEventHandlers
async def main() -> None:
    async with AsyncStreamingClient(api_key="your_api_key_here") as client:
        await client.connect(PrintingEventHandlers())
        with open("audio.pcm", "rb") as f:
            while chunk := f.read(16000):
                await client.send_audio(chunk)
        await client.flush()
if __name__ == "__main__":
    asyncio.run(main())