Skip to main content

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)

Performance Optimization

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

Community & Support

Getting Help

  1. Documentation - Check our comprehensive guides and API reference
  2. GitHub Issues - Search existing issues or create a new one
  3. Email Support - support@verbalisai.com for urgent issues
  4. Community Slack - Join discussions at verbalisai.slack.com

Resources

Ready to get started? Check out our installation guide and dive into the Python or JavaScript quickstart tutorials.
I