Getting Started with Vagary Voice

Everything you need to integrate Vagary Voice into your applications. Follow this guide to get up and running in minutes.

New to Vagary Voice?

Start with our Quick Start Guide below to set up your first integration in under 5 minutes.

Installation

Install the Vagary Voice SDK using your preferred package manager:

Not published yet. These are the canonical package names, but they have not been released to npm or PyPI. Build against them — the commands will start working when the first release ships.

npm

npm install @vagary/voice-sdk

yarn

yarn add @vagary/voice-sdk

pnpm

pnpm add @vagary/voice-sdk

For Python applications:

Not published yet. Same as above — this is the canonical PyPI name, but it has not been released.

pip

pip install vagary-voice

Authentication

All API requests require authentication using an API key. You can create and manage API keys in your dashboard.

Using API Keys

Include your API key in the X-API-Key header. The API checks this header before falling back to session auth, so this is the header a server-to-server integration should send.

Bash

1curl https://api.vagaryvoice.cloud/bots \
2  -H "X-API-Key: $VAGARY_API_KEY"

Security Best Practice

Never expose your API key in client-side code. Always make API calls from your server or use environment variables.

Rate Limits

API rate limits vary by plan. Rate limit information is included in response headers.

Plan	Requests/min	Concurrent
Free	10	1
Pro	100	10
Enterprise	1000+	Unlimited

Speech-to-Text API

Convert audio to text with industry-leading accuracy. Supports 100+ languages with speaker diarization and punctuation.

Quick Start

Python

1from vagary_voice import VagaryVoice
2 
3# Initialize client
4client = VagaryVoice(api_key="your_api_key")
5 
6# Transcribe audio file
7result = client.transcribe(
8    audio_file="audio.mp3",
9    language="en-US",
10    enable_diarization=True
11)
12 
13print(result.transcript)
14print(result.speakers)

JavaScript

1import { VagaryVoice } from '@vagary/voice-sdk';
2 
3// Initialize client
4const client = new VagaryVoice({
5  apiKey: process.env.VAGARY_API_KEY
6});
7 
8// Transcribe audio file
9const result = await client.transcribe({
10  audioUrl: 'https://example.com/audio.mp3',
11  language: 'en-US',
12  enableDiarization: true
13});
14 
15console.log(result.transcript);
16console.log(result.speakers);

Options

languagestring

Language code for transcription (e.g., "en-US", "es-ES", "ja-JP")

enable_diarizationboolean

Enable speaker diarization to identify different speakers

punctuateboolean

Add punctuation to the transcript (default: true)

Text-to-Speech API

Generate natural-sounding speech from text with customizable voices, emotions, and speaking styles.

JavaScript

1import { VagaryVoice } from '@vagary/voice-sdk';
2 
3const client = new VagaryVoice({
4  apiKey: process.env.VAGARY_API_KEY
5});
6 
7// Synthesize speech
8const audio = await client.synthesize({
9  text: 'Hello from Vagary Voice!',
10  voice: 'en-US-Neural-Female',
11  emotion: 'friendly',
12  speed: 1.0
13});
14 
15// Save to file
16await audio.save('output.mp3');
17 
18// Or stream directly
19const stream = audio.stream();

WebSocket API

Real-time streaming for low-latency transcription. Perfect for live applications like voice assistants and live captioning.

Real-time Streaming

1const stream = client.streamTranscribe({
2  language: 'en-US',
3  interimResults: true,
4  endpointing: {
5    silenceThreshold: 500,
6    maxUtteranceLength: 30000
7  }
8});
9 
10// Handle transcription results
11stream.on('transcript', (data) => {
12  if (data.isFinal) {
13    console.log('Final:', data.text);
14  } else {
15    console.log('Interim:', data.text);
16  }
17});
18 
19// Handle errors
20stream.on('error', (error) => {
21  console.error('Stream error:', error);
22});
23 
24// Send audio data from microphone
25navigator.mediaDevices.getUserMedia({ audio: true })
26  .then(mediaStream => {
27    const recorder = new MediaRecorder(mediaStream);
28    recorder.ondataavailable = (e) => {
29      stream.write(e.data);
30    };
31    recorder.start(100); // Send chunks every 100ms
32  });

Voice Management

Browse available voices or create custom voice clones for your brand.

List Available Voices

JavaScript

1const voices = await client.listVoices({
2  language: 'en-US',
3  gender: 'female'
4});
5 
6voices.forEach(voice => {
7  console.log(`${voice.name} - ${voice.description}`);
8});

Voice Cloning

Create a custom voice clone from audio samples. Requires at least 3 minutes of clear audio.

Python

1# Create a voice clone
2clone = client.create_voice_clone(
3    name="My Custom Voice",
4    audio_files=[
5        "sample1.mp3",
6        "sample2.mp3",
7        "sample3.mp3"
8    ],
9    description="A warm, friendly voice for customer support"
10)
11 
12print(f"Voice clone created: {clone.id}")
13 
14# Use the cloned voice
15audio = client.synthesize(
16    text="Hello, how can I help you today?",
17    voice=clone.id
18)

Error Codes

Standard HTTP status codes are used for all responses. Error responses include a code and message for debugging.

Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid API key
403	Forbidden - Insufficient permissions
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Error Response Format

1{
2  "error": {
3    "code": "invalid_audio_format",
4    "message": "Unsupported audio format. Please use MP3, WAV, or FLAC.",
5    "details": {
6      "supported_formats": ["mp3", "wav", "flac", "ogg", "webm"]
7    }
8  }
9}

Python SDK

The Python SDK provides a Pythonic interface for all Vagary Voice APIs.

Not published yet. This is the canonical package name (ADR-122), but it has not been released yet. The install command below will start working once the first release ships — use the raw HTTP API until then.

Bash

pip install vagary-voice

Python

1from vagary_voice import VagaryVoice
2import os
3 
4# Initialize with environment variable
5client = VagaryVoice(api_key=os.getenv("VAGARY_API_KEY"))
6 
7# List your bots, then place a call through one of them
8bots = client.list_bots()
9call = client.initiate_call(
10    to="+14155551234",
11    from_="+14155550000",
12    bot_id=bots.bots[0].id,
13    provider="twilio",
14    recording_enabled=True,
15)
16status = client.get_call_status(call["call_id"])

JavaScript SDK

Works in Node.js and modern browsers with full TypeScript support.

Bash

npm install @vagary/voice-sdk

JavaScript

1import { VagaryVoice } from '@vagary/voice-sdk';
2 
3// The constructor takes positional args: apiKey, then an optional baseUrl override.
4const client = new VagaryVoice(process.env.VAGARY_API_KEY);
5 
6// List your bots, then place a call through one of them
7const { bots } = await client.listBots();
8const call = await client.initiateCall({
9  to: '+14155551234',
10  from: '+14155550000',
11  bot_id: bots[0].id,
12  provider: 'twilio',
13  recording_enabled: true,
14});
15const status = await client.getCallStatus(call.call_id);

Webhooks

Receive real-time notifications when transcription jobs complete or other events occur.

Setting Up Webhooks

JavaScript

1// When creating a transcription job, specify webhook URL
2const job = await client.transcribe({
3  audioUrl: 'https://example.com/audio.mp3',
4  webhook: {
5    url: 'https://yourapp.com/webhooks/vagary',
6    events: ['transcription.completed', 'transcription.failed']
7  }
8});
9 
10// Your webhook endpoint receives:
11{
12  "event": "transcription.completed",
13  "timestamp": "2024-01-15T10:30:00Z",
14  "data": {
15    "job_id": "job_abc123",
16    "transcript": "Hello, this is the transcribed text...",
17    "duration_seconds": 45.2
18  }
19}

Webhook Security

Verify webhook signatures to ensure requests come from Vagary Voice.

JavaScript

1import { verifyWebhookSignature } from '@vagary/voice-sdk';
2 
3app.post('/webhooks/vagary', (req, res) => {
4  const signature = req.headers['x-vagary-signature'];
5  const isValid = verifyWebhookSignature(
6    req.body,
7    signature,
8    process.env.VAGARY_WEBHOOK_SECRET
9  );
10 
11  if (!isValid) {
12    return res.status(401).send('Invalid signature');
13  }
14 
15  // Process the webhook
16  const { event, data } = req.body;
17  console.log(`Received ${event}`, data);
18 
19  res.status(200).send('OK');
20});

Best Practices

1. Use Appropriate Audio Formats

For best results, use lossless formats (WAV, FLAC) for high-quality audio. MP3 at 128kbps+ is acceptable for most use cases.

2. Handle Rate Limits Gracefully

Implement exponential backoff when receiving 429 errors. Check theRetry-Afterheader for guidance.

3. Use Streaming for Real-time Applications

For live transcription, use the WebSocket API to minimize latency. The REST API is better suited for batch processing.

4. Secure Your API Keys

Never expose API keys in client-side code. Use environment variables and server-side proxies to protect credentials.

Need Help?

Our support team is here to help you succeed with Vagary Voice.

Contact Support View on GitHub