Server-Side SDKs

Build voice-enabled backends with VocaFuse. Generate tokens for frontend authentication, manage voice notes, and receive transcriptions via webhooks.

---

Available SDKs

VocaFuse currently provides:

• Python SDK — Full-featured SDK for Python applications with support for Flask, Django, FastAPI, and other frameworks
• Node.js SDK — Official Node.js/TypeScript SDK for Express, Next.js, NestJS, and other JavaScript backends

---

Key Features

Server-Side SDKs provide the following capabilities:

• Authentication — Generate JWT tokens for client applications
• Voice Note Management — List, retrieve, and delete voice notes
• Transcription Access — Retrieve transcription data with confidence scores
• Webhook Configuration — Set up and manage webhook endpoints
• Signature Validation — Verify webhook authenticity

---

When to Use Server-Side SDKs

Use Server-Side SDKs when you need to:

• Generate JWT tokens for your client applications to authenticate with VocaFuse
• Retrieve voice notes and transcriptions from your backend
• Manage voice note data programmatically
• Configure and validate webhooks
• Build server-side integrations with VocaFuse

---

Install

Python

pip install vocafuse

Node.js

npm install vocafuse-node

Or add to requirements.txt:

vocafuse>=1.0.0

---

Initialize

Python

from vocafuse import Client
import os

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

Node.js

const { Client } = require('vocafuse-node');

const client = new Client({
  apiKey: process.env.VOCAFUSE_API_KEY,
  apiSecret: process.env.VOCAFUSE_API_SECRET,
});

Get your API keys from the VocaFuse dashboard.

---

Basic Operations

Python

# List voice notes
recordings = client.recordings.list(limit=10)

# Get a specific voice note
recording = client.recordings.get('rec_123')

# Get transcription
transcription = client.recordings('rec_123').transcription.get()
print(transcription['text'])

# Delete
client.recordings('rec_123').delete()

Node.js

// List voice notes
const recordings = await client.recordings.list({ limit: 10 });

// Get a specific voice note
const recording = await client.recordings('rec_123').get();

// Get transcription
const transcription = await client.recordings('rec_123').transcription.get();
console.log(transcription.data.text);

// Delete
await client.recordings('rec_123').delete();

---

Generate Frontend Tokens

Your frontend needs a token to upload audio. Create an endpoint that generates tokens:

Python

from vocafuse import AccessToken

@app.route('/api/vocafuse-token', methods=['POST'])
def generate_token():
    token = AccessToken(
        api_key=os.environ['VOCAFUSE_API_KEY'],
        api_secret=os.environ['VOCAFUSE_API_SECRET'],
        identity=str(current_user.id)
    )
    return jsonify(token(expires_in=3600))

Node.js

const express = require('express');
const { AccessToken } = require('vocafuse-node');

const app = express();

app.post('/api/vocafuse-token', async (req, res) => {
  // Replace with your own auth logic
  const userId = req.user?.id || 'user_123';

  const token = new AccessToken({
    apiKey: process.env.VOCAFUSE_API_KEY,
    apiSecret: process.env.VOCAFUSE_API_SECRET,
    identity: String(userId),
  });

  const response = await token.generate({ expiresIn: 3600 });
  res.json(response.data);
});

---

Handle Webhooks

Receive transcription results when processing completes:

Python

from vocafuse import RequestValidator

validator = RequestValidator(os.environ['VOCAFUSE_WEBHOOK_SECRET'])

@app.route('/api/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()
    if data['event'] == 'recording.transcribed':
        print(data['recording']['transcription']['text'])
    
    return {'status': 'received'}, 200

Node.js

const express = require('express');
const { RequestValidator } = require('vocafuse-node');

const app = express();
app.use(express.json());

const validator = new RequestValidator(process.env.VOCAFUSE_WEBHOOK_SECRET);

app.post('/api/webhooks/vocafuse', (req, res) => {
  const payload = JSON.stringify(req.body);
  const signature = req.headers['x-vocafuse-signature'];

  if (!validator.validate(payload, signature)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const { event, recording } = req.body;

  if (event === 'recording.transcribed') {
    console.log(recording.transcription.text);
  }

  return res.json({ status: 'received' });
});

---

Security

Server-Side SDKs use your API Key and API Secret for authentication. These credentials should:

• ✅ Be stored securely in environment variables
• ✅ Never be exposed in client-side code
• ✅ Be kept confidential and rotated regularly
• ✅ Have appropriate access controls on your servers

API Credentials

Never commit API credentials to version control. Always use environment variables or secure credential management systems.

---

Next Steps

Goal	Resource
Build complete speech-to-text backend	Python Tutorial →
Configure timeouts, retries, errors	Configuration →
Explore all API endpoints	API Reference →
Production webhook patterns	Webhooks Guide →