orbitalsai 1.1.0

A simple and powerful Python SDK for the OrbitalsAI API

OrbitalsAI Python SDK

A simple and powerful Python SDK for the OrbitalsAI API. Transcribe audio files in multiple African languages with optional SRT subtitle generation.

✨ Features

• 🚀 Simple API - Just 3 lines to transcribe audio
• 🔄 Sync & Async - Use synchronously or asynchronously
• 🌍 African Languages - Support for Hausa, Igbo, Yoruba, Swahili, and more
• 📝 SRT Subtitles - Generate subtitle files automatically
• 💰 Balance Management - Built-in billing and usage tracking
• 🔒 Secure - API key authentication
• 📦 Easy Installation - pip install orbitalsai

🚀 Quick Start

Installation

pip install orbitalsai

Basic Usage

import orbitalsai

# Initialize client
client = orbitalsai.Client(api_key="your_api_key_here")

# Transcribe audio (waits automatically)
transcript = client.transcribe("audio.mp3")
print(transcript.text)

That's it! 🎉

📖 Table of Contents

• Installation
• Quick Start
• Authentication
• Basic Transcription
• Advanced Features
• Async Usage
• Error Handling
• API Reference
• Supported Languages
• Supported Formats
• Troubleshooting

🔑 Authentication

Get your API key from the OrbitalsAI Dashboard.

import orbitalsai

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

🎵 Basic Transcription

Simple Transcription

import orbitalsai

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

# Transcribe audio file
transcript = client.transcribe("audio.mp3")
print(transcript.text)

With Language and SRT

import orbitalsai

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

# Transcribe in Hausa with SRT subtitles
transcript = client.transcribe(
    "audio.mp3",
    language="hausa",
    generate_srt=True
)

print(transcript.text)
print(transcript.srt_content)  # SRT subtitle content

🤖 AI Model Selection

Choose which AI model to use for transcription. Different models may have different pricing and capabilities.

List Available Models

import orbitalsai

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

# Get all available models
models = client.get_models()

for model in models:
    print(f"{model.model_name}: ${model.transcription_rate_per_hour:.2f}/hour")

Transcribe with Specific Model

import orbitalsai

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

# Transcribe with Perigee-1 model
transcript = client.transcribe(
    "audio.mp3",
    language="hausa",
    model_name="Perigee-1"  # Specify the model
)

print(transcript.text)

Choose Model Based on Budget

import orbitalsai

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

# Get the cheapest available model
models = client.get_models()
cheapest_model = min(models, key=lambda m: m.transcription_rate_per_hour)

print(f"Using {cheapest_model.model_name} at ${cheapest_model.transcription_rate_per_hour:.2f}/hour")

transcript = client.transcribe(
    "audio.mp3",
    language="english",
    model_name=cheapest_model.model_name
)

🔄 Async Usage

Perfect for processing multiple files or building web applications.

import asyncio
import orbitalsai

async def main():
    async with orbitalsai.AsyncClient(api_key="your_api_key_here") as client:
        # List available models
        models = await client.get_models()
        print(f"Available models: {[m.model_name for m in models]}")
        
        # Transcribe multiple files concurrently
        tasks = await asyncio.gather(
            client.transcribe("audio1.mp3", model_name="Perigee-1"),
            client.transcribe("audio2.wav", model_name="Perigee-1"),
            client.transcribe("audio3.m4a", model_name="Perigee-1")
        )
        
        for transcript in tasks:
            print(transcript.text)

asyncio.run(main())

💰 Balance Management

Check Balance

import orbitalsai

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

balance = client.get_balance()
print(f"Current balance: ${balance.balance:.2f}")
print(f"Last updated: {balance.last_updated}")

Usage History

import orbitalsai
from datetime import date, timedelta

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

# Get last 7 days of usage
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"Total cost: ${usage.total_cost:.2f}")
print(f"Total audio processed: {usage.total_audio_seconds:.1f} seconds")

for day in usage.daily_records:
    print(f"{day.date}: ${day.total_cost:.4f} ({day.transcription_usage:.1f}s transcription)")

🛠️ Advanced Features

List All Tasks

import orbitalsai

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

tasks = client.list_tasks()
for task in tasks:
    print(f"Task {task.task_id}: {task.status} - {task.original_filename}")

Get User Information

import orbitalsai

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

user = client.get_user()
print(f"User: {user.first_name} {user.last_name} ({user.email})")
print(f"Verified: {user.is_verified}")

⚠️ Error Handling

The SDK provides specific exceptions for different error scenarios.

import orbitalsai
from orbitalsai.exceptions import (
    AuthenticationError, InsufficientBalanceError, 
    UnsupportedFileError, UnsupportedLanguageError,
    TranscriptionError, TimeoutError
)

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

try:
    transcript = client.transcribe("audio.mp3", language="hausa")
    print(transcript.text)
    
except UnsupportedFileError:
    print("File format not supported")
except UnsupportedLanguageError:
    print("Language not supported")
except InsufficientBalanceError:
    print("Not enough credits")
except AuthenticationError:
    print("Invalid API key")
except TranscriptionError as e:
    print(f"Transcription failed: {e}")
except TimeoutError:
    print("Transcription timed out")
except Exception as e:
    print(f"Unexpected error: {e}")

📚 API Reference

Client Methods

get_models()

Get all available AI models with their pricing information.

Returns: List of Model objects

transcribe(file_path, language="english", generate_srt=False, model_name="Perigee-1", wait=True, timeout=300, poll_interval=5)

Transcribe an audio file.

Parameters:

• file_path (str): Path to the audio file
• language (str): Language code (default: "english")
• generate_srt (bool): Generate SRT subtitles (default: False)
• model_name (str): AI model to use (default: "Perigee-1")
• wait (bool): Wait for completion (default: True)
• timeout (int): Maximum wait time in seconds (default: 300)
• poll_interval (int): Seconds between status checks (default: 5)

Returns: Transcript object (if wait=True) or TranscriptTask object (if wait=False)

get_task(task_id)

Get the status of a transcription task.

Parameters:

• task_id (int): ID of the task

Returns: TranscriptTask object

wait_for_task(task_id, timeout=300, poll_interval=5)

Wait for a task to complete.

Parameters:

• task_id (int): ID of the task
• timeout (int): Maximum wait time in seconds
• poll_interval (int): Seconds between status checks

Returns: Transcript object

list_tasks()

Get all transcription tasks for the current user.

Returns: List of TranscriptTask objects

get_balance()

Get the current user's balance.

Returns: Balance object

get_usage_history(start_date=None, end_date=None, page=1, page_size=50)

Get usage history for the current user.

Returns: UsageHistory object

get_daily_usage(start_date=None, end_date=None, page=1, page_size=30)

Get daily usage history for the current user.

Returns: DailyUsage object

get_user()

Get current user details.

Returns: User object

Data Models

Transcript

• text (str): Transcribed text
• srt_content (str, optional): SRT subtitle content
• task_id (int): Task ID
• original_filename (str): Original filename
• audio_url (str, optional): URL to processed audio

TranscriptTask

• task_id (int): Task ID
• status (str): Task status ("pending", "processing", "completed", "failed")
• original_filename (str): Original filename
• audio_url (str, optional): URL to processed audio
• srt_requested (bool): Whether SRT was requested
• result_text (str, optional): Transcribed text
• srt_content (str, optional): SRT subtitle content
• error (str, optional): Error message if failed

Balance

• balance (float): Current balance in credits
• last_updated (datetime): Last update timestamp

Model

• id (int): Model ID
• model_name (str): Name of the model (e.g., "Perigee-1")
• transcription_rate_per_second (float): Cost per second of audio
• transcription_rate_per_hour (float): Cost per hour of audio
• is_active (bool): Whether the model is currently available

🌍 Supported Languages

• English (english)
• Hausa (hausa)
• Igbo (igbo)
• Yoruba (yoruba)
• Swahili (swahili)
• Pidgin (pidgin)
• Kinyarwanda (kinyarwanda)

📁 Supported Formats

Audio Formats

• WAV (.wav, .wave)
• MP3 (.mp3, .mpeg)
• OGG (.ogg, .oga)
• FLAC (.flac)
• AAC (.aac)
• M4A (.m4a)
• WMA (.wma)
• AMR (.amr)
• 3GP (.3gp)

Maximum File Size

• 200 MB per file

🔧 Troubleshooting

Common Issues

Q: I get "Invalid API key" error A: Make sure your API key is correct. Get it from the OrbitalsAI Dashboard.

Q: I get "Insufficient balance" error A: Add credits to your account through the dashboard.

Q: I get "Unsupported file format" error A: Make sure your audio file is in a supported format (see Supported Formats).

Q: Transcription takes too long A: Large files take longer to process. You can increase the timeout:

transcript = client.transcribe("large_file.mp3", timeout=600)  # 10 minutes

Q: I get "Unsupported language" error A: Make sure you're using a supported language code (see Supported Languages).

Getting Help

• 📧 Email: [e-mail]
• 🐛 Issues: GitHub Issues
• 📖 Docs: Documentation

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🙏 Acknowledgments

• Built for the African AI community
• Powered by OrbitalsAI

---

Made by the OrbitalsAI team