VerbalisAI SDKs
VerbalisAI provides official SDK libraries for Python and JavaScript that simplify integration with our audio transcription and file storage API.
Available SDKs
Key SDK Features
- Simple Authentication - Automatic API key management
- Type Safety - Full TypeScript support for JavaScript SDK
- Error Handling - Robust error handling with detailed messages
- Async/Await Support - Modern asynchronous API
- File Upload - Easy audio file upload and management
- Webhooks - Support for webhook notifications
- Rate Limiting - Automatic rate limit handling with retries
Quick Start
Python
from verbalisai import VerbalisAI
client = VerbalisAI(api_key="your-api-key")
# Transcribe audio file
transcription = await client.transcriptions.create(
audio_url="https://example.com/audio.mp3",
model="mini",
topics=True,
summarization=True
)
print(transcription.text)
print(transcription.topics)
print(transcription.summary.text)
JavaScript
import { VerbalisAI } from 'verbalisai';
const client = new VerbalisAI({
apiKey: 'your-api-key'
});
// Transcribe audio file
const transcription = await client.transcriptions.create({
audioUrl: 'https://example.com/audio.mp3',
model: 'mini',
topics: true,
summarization: true
});
console.log(transcription.text);
console.log(transcription.topics);
console.log(transcription.summary.text);
Installation
See detailed installation instructions on the installation page.
API Coverage
Both SDKs provide complete coverage of the VerbalisAI API:
- Transcription API - Create, retrieve, and manage transcriptions
- File Storage API - Upload, download, and manage audio files
- Usage & Analytics - Track usage and monitor transcription analytics
- Authentication - API key management and OAuth support
Error Handling
SDKs provide comprehensive error handling for common scenarios:
- Network connectivity issues
- API rate limiting
- Authentication failures
- Invalid parameters
- Server errors
Support
- GitHub Issues - For bug reports and feature requests
- Email Support - support@verbalisai.com
- Documentation - Complete API reference and examples
- Community - Slack community for discussions
Advanced Features
Async Processing with Webhooks
# Python - Set up webhook for long audio processing
transcription = await client.transcriptions.create(
audio_url="https://example.com/long-audio.mp3",
model="pro",
webhook_url="https://yoursite.com/webhook",
webhook_auth_header_name="Authorization",
webhook_auth_header_value="Bearer your-webhook-secret",
wait_until_complete=False # Don't wait, use webhook
)
print(f"Transcription started: {transcription.id}")
// JavaScript - Set up webhook for long audio processing
const transcription = await client.transcriptions.create({
audioUrl: 'https://example.com/long-audio.mp3',
model: 'pro',
webhookUrl: 'https://yoursite.com/webhook',
webhookAuthHeaderName: 'Authorization',
webhookAuthHeaderValue: 'Bearer your-webhook-secret',
waitUntilComplete: false // Don't wait, use webhook
});
console.log(`Transcription started: ${transcription.id}`);
Speaker Diarization
# Python - Identify different speakers
transcription = await client.transcriptions.create(
audio_url="https://example.com/meeting.mp3",
model="mini",
diarize=True,
timestamp_style="word"
)
for segment in transcription.segments:
print(f"Speaker {segment.speaker_id}: {segment.text}")
PII Redaction
# Python - Remove sensitive information
transcription = await client.transcriptions.create(
audio_url="https://example.com/call.mp3",
redact_pii=True,
redact_pii_policies=["person", "email", "phone_number", "ssn"],
redact_pii_sub="hash"
)
# Sensitive data will be automatically redacted
print(transcription.text) # "Hi my name is [REDACTED] and my phone is [REDACTED]"
File Management
Upload Audio Files
# Python - Upload and transcribe local file
with open("audio.mp3", "rb") as audio_file:
# Upload file to storage
file_info = await client.files.upload(
file=audio_file,
filename="audio.mp3"
)
# Transcribe uploaded file
transcription = await client.transcriptions.create(
audio_url=file_info.url,
model="mini"
)
// JavaScript - Upload and transcribe local file
const fileInput = document.getElementById('audioFile');
const file = fileInput.files[0];
// Upload file to storage
const fileInfo = await client.files.upload({
file: file,
filename: file.name
});
// Transcribe uploaded file
const transcription = await client.transcriptions.create({
audioUrl: fileInfo.url,
model: 'mini'
});
Usage Analytics
# Python - Track your usage
usage = await client.usage.get_overview()
print(f"Credits used this month: {usage.credits_used}")
print(f"Total transcriptions: {usage.total_transcriptions}")
# Get detailed analytics
analytics = await client.usage.get_analytics(
start_date="2024-01-01",
end_date="2024-01-31"
)
Configuration Options
Client Configuration
# Python - Advanced client configuration
client = VerbalisAI(
api_key="your-api-key",
base_url="https://api.verbalisai.com/api", # Custom base URL
timeout=60, # Request timeout in seconds
max_retries=3, # Retry failed requests
retry_delay=1.0 # Delay between retries
)
// JavaScript - Advanced client configuration
const client = new VerbalisAI({
apiKey: 'your-api-key',
baseUrl: 'https://api.verbalisai.com/api', // Custom base URL
timeout: 60000, // Request timeout in milliseconds
maxRetries: 3, // Retry failed requests
retryDelay: 1000 // Delay between retries
});
Environment Variables
Set these environment variables for automatic configuration:
VERBALISAI_API_KEY=your-api-key
VERBALISAI_BASE_URL=https://api.verbalisai.com/api
VERBALISAI_TIMEOUT=30
VERBALISAI_MAX_RETRIES=3
Best Practices
Error Handling
# Python - Comprehensive error handling
from verbalisai import VerbalisAI, VerbalisAIError
client = VerbalisAI(api_key="your-api-key")
try:
transcription = await client.transcriptions.create(
audio_url="https://example.com/audio.mp3"
)
except VerbalisAIError as e:
if e.status_code == 429:
print("Rate limit exceeded, please try again later")
elif e.status_code == 401:
print("Invalid API key")
elif e.status_code == 400:
print(f"Bad request: {e.message}")
else:
print(f"API error: {e.message}")
except Exception as e:
print(f"Unexpected error: {e}")
Resource Management
# Python - Use context manager for automatic cleanup
async with VerbalisAI(api_key="your-api-key") as client:
transcription = await client.transcriptions.create(
audio_url="https://example.com/audio.mp3"
)
print(transcription.text)
# Client automatically cleaned up
Batch Processing
# Python - Process multiple files efficiently
audio_urls = [
"https://example.com/audio1.mp3",
"https://example.com/audio2.mp3",
"https://example.com/audio3.mp3"
]
import asyncio
async def transcribe_batch(urls):
tasks = []
for url in urls:
task = client.transcriptions.create(audio_url=url, model="mini")
tasks.append(task)
results = await asyncio.gather(*tasks, return_exceptions=True)
return results
transcriptions = await transcribe_batch(audio_urls)
Model Selection
Choose the right model for your use case:
- nano - Fastest processing, English only, best for real-time applications
- mini - Balanced speed and accuracy, supports multiple languages
- pro - Highest accuracy, best for professional transcriptions
Preprocessing Tips
- Use supported audio formats (MP3, WAV, FLAC recommended)
- Ensure good audio quality (16kHz+ sample rate)
- Remove silence at the beginning/end for faster processing
- Split very long audio files (>2 hours) for better performance
Contributing
SDKs are open-source projects and we welcome contributions from the community:
Python SDK
JavaScript SDK
Development Setup
# Python SDK development
git clone https://github.com/verbalisai/python-sdk.git
cd python-sdk
pip install -e ".[dev]"
pytest
# JavaScript SDK development
git clone https://github.com/verbalisai/js-sdk.git
cd js-sdk
npm install
npm test
Getting Help
- Documentation - Check our comprehensive guides and API reference
- GitHub Issues - Search existing issues or create a new one
- Email Support - support@verbalisai.com for urgent issues
- Community Slack - Join discussions at verbalisai.slack.com
Resources
Responses are generated using AI and may contain mistakes.
