Python Voice Notes SDK

Server-side voice notes integration for Flask, Django, and FastAPI. Generate authentication tokens, manage voice notes, configure webhooks, and retrieve transcriptions programmatically. Fully typed with Python 3.7+ support.

Installation

pip install vocafuse

Or add to requirements.txt:

vocafuse>=1.0.0

Quick Start

Python

from vocafuse import Client

client = Client(
    api_key='sk_live_...',
    api_secret='...'
)

# List voicenotes
voicenotes = client.voicenotes.list(limit=10)

# Get specific voicenote
voicenote = client.voicenotes.get('rec_123')

# Get transcription
transcription = client.voicenotes('rec_123').transcription.get()

Authentication

Initialize Client

From Environment

import os
from vocafuse import Client

client = Client(
    api_key=os.environ['VOCAFUSE_API_KEY'],
    api_secret=os.environ['VOCAFUSE_API_SECRET']
)

Direct Credentials

from vocafuse import Client

client = Client(
    api_key='sk_live_...',
    api_secret='your_secret'
)

Generate Access Tokens

Create JWT tokens for frontend authentication:

Python

from vocafuse import AccessToken

token = AccessToken(
    api_key='sk_live_...',
    api_secret='...',
    identity='user_12345'
)

result = token(expires_in=3600)
print(result['token'])

Working with the API

The Python SDK provides convenient methods for all VocaFuse API endpoints:

Python

# Voice Notes - see API Reference for full details
voicenotes = client.voicenotes.list(limit=10, status='transcribed')
voicenote = client.voicenotes.get('rec_123')
transcription = client.voicenotes('rec_123').transcription.get()
client.voicenotes('rec_123').delete()

# Webhooks - see API Reference for full details
webhook = client.webhooks.create(
    url='https://example.com/webhook',
    events=['voicenote.transcribed']
)
webhooks = client.webhooks.list()
client.webhooks('webhook_123').delete()

For complete API documentation including all parameters, response formats, and examples, see:

• Voice Notes API Reference
• Webhooks API Reference

Webhook Signature Validation

Python

import os
from flask import Flask, request
from vocafuse import Client, RequestValidator

app = Flask(__name__)

client = Client(
    api_key='sk_live_...',
    api_secret='...'
)

validator = RequestValidator('your_webhook_secret')

@app.route('/webhooks/vocafuse', methods=['POST'])
def handle_webhook():
    payload = request.get_data(as_text=True)
    signature = request.headers.get('X-VocaFuse-Signature')
    
    if not validator.validate(payload, signature):
        return {'error': 'Invalid signature'}, 401
    
    data = request.get_json()
    # Process webhook...
    
    return {'status': 'received'}, 200

Configuration

Timeout

Python

client = Client(
    api_key='sk_live_...',
    api_secret='...',
    timeout=30  # 30 seconds
)

Retry Configuration

Python

client = Client(
    api_key='sk_live_...',
    api_secret='...',
    max_retries=3,
    retry_delay=1.0
)

Debug Logging

Python

import logging

logging.basicConfig(level=logging.DEBUG)

client = Client(
    api_key='sk_live_...',
    api_secret='...',
    debug=True
)

Error Handling

The SDK raises specific exceptions for different error scenarios:

Python

from vocafuse import Client, VocaFuseError, AuthenticationError, RateLimitError

try:
    voicenote = client.voicenotes.get('rec_123')
except AuthenticationError:
    print('Invalid API credentials')
except RateLimitError as e:
    print(f'Rate limited. Retry after {e.retry_after} seconds')
except VocaFuseError as e:
    print(f'API error: {e.message}')

Exception Types

Exception	Description
VocaFuseError	Base exception for all API errors
AuthenticationError	Invalid API credentials
RateLimitError	Rate limit exceeded
ValidationError	Invalid request parameters
NotFoundError	Resource not found

See Error Handling Reference for complete error codes and troubleshooting.

Framework Integration

Flask

Python

from flask import Flask, request, jsonify
from vocafuse import Client, AccessToken, RequestValidator
import os

app = Flask(__name__)

client = Client(
    api_key=os.environ['VOCAFUSE_API_KEY'],
    api_secret=os.environ['VOCAFUSE_API_SECRET']
)

# Generate tokens for client authentication
@app.route('/api/vocafuse-token', methods=['POST'])
def generate_token():
    user_id = get_current_user()
    
    token = AccessToken(
        api_key=os.environ['VOCAFUSE_API_KEY'],
        api_secret=os.environ['VOCAFUSE_API_SECRET'],
        identity=str(user_id)
    )
    
    return jsonify(token(expires_in=3600))

# Handle webhook notifications
@app.route('/api/webhooks/vocafuse', methods=['POST'])
def handle_webhook():
    validator = RequestValidator(os.environ['VOCAFUSE_WEBHOOK_SECRET'])
    
    payload = request.get_data(as_text=True)
    signature = request.headers.get('X-VocaFuse-Signature')
    
    if not validator.validate(payload, signature):
        return jsonify({'error': 'Invalid signature'}), 401
    
    data = request.get_json()
    
    if data['event'] == 'voicenote.transcribed':
        voicenote_id = data['voicenote']['id']
        transcription = client.voicenotes(voicenote_id).transcription.get()
        # Process transcription...
    
    return jsonify({'status': 'received'}), 200

Django

Python

from django.http import JsonResponse
from django.views.decorators.csrf import csrf_exempt
from vocafuse import Client, AccessToken, RequestValidator
import os

client = Client(
    api_key=os.environ['VOCAFUSE_API_KEY'],
    api_secret=os.environ['VOCAFUSE_API_SECRET']
)

def generate_token(request):
    user_id = request.user.id
    
    token = AccessToken(
        api_key=os.environ['VOCAFUSE_API_KEY'],
        api_secret=os.environ['VOCAFUSE_API_SECRET'],
        identity=str(user_id)
    )
    
    return JsonResponse(token(expires_in=3600))

@csrf_exempt
def handle_webhook(request):
    validator = RequestValidator(os.environ['VOCAFUSE_WEBHOOK_SECRET'])
    
    payload = request.body.decode('utf-8')
    signature = request.headers.get('X-VocaFuse-Signature')
    
    if not validator.validate(payload, signature):
        return JsonResponse({'error': 'Invalid signature'}, status=401)
    
    data = json.loads(payload)
    # Process webhook...
    
    return JsonResponse({'status': 'received'})

FastAPI

Python

from fastapi import FastAPI, Request, HTTPException
from vocafuse import Client, AccessToken, RequestValidator
import os

app = FastAPI()

client = Client(
    api_key=os.environ['VOCAFUSE_API_KEY'],
    api_secret=os.environ['VOCAFUSE_API_SECRET']
)

@app.post('/api/vocafuse-token')
async def generate_token(request: Request):
    user_id = get_current_user(request)
    
    token = AccessToken(
        api_key=os.environ['VOCAFUSE_API_KEY'],
        api_secret=os.environ['VOCAFUSE_API_SECRET'],
        identity=str(user_id)
    )
    
    return token(expires_in=3600)

@app.post('/api/webhooks/vocafuse')
async def handle_webhook(request: Request):
    validator = RequestValidator(os.environ['VOCAFUSE_WEBHOOK_SECRET'])
    
    payload = await request.body()
    signature = request.headers.get('X-VocaFuse-Signature')
    
    if not validator.validate(payload.decode(), signature):
        raise HTTPException(status_code=401, detail='Invalid signature')
    
    data = await request.json()
    # Process webhook...
    
    return {'status': 'received'}