Voxa Backend API

Node.js/Express backend for Voxa real-time translation app, deployable on Render.com.

Features

• ✅ Translation API (Gemini 2.5 Pro)
• ✅ Text-to-Speech API (Gemini 2.5 Pro Preview TTS)
• ✅ Command parsing
• ✅ Request caching (10-minute TTL)
• ✅ Rate limiting (60 req/min)
• ✅ API key authentication
• ✅ CORS support
• ✅ Compression
• ✅ Health checks

Quick Start

Local Development

cd backend

# Install dependencies
npm install

# Create .env file
cp .env.example .env

# Edit .env and add your Gemini API key
nano .env

# Start development server
npm run dev

Server will run on http://localhost:3000

Test Endpoints

# Health check
curl http://localhost:3000/health

# Translation (with API key)
curl -X POST http://localhost:3000/api/translate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_secret" \
  -d '{
    "text": "Hello, how are you?",
    "sourceLanguage": "en",
    "targetLanguage": "ko",
    "tone": "neutral"
  }'

# TTS
curl -X POST http://localhost:3000/api/tts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_secret" \
  -d '{
    "text": "안녕하세요",
    "languageCode": "ko-KR"
  }'

# Command parsing
curl -X POST http://localhost:3000/api/command \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_secret" \
  -d '{
    "command": "switch to Japanese"
  }'

Deploy to Render.com

Step 1: Prepare Repository

# Initialize git (if not already done)
cd backend
git init
git add .
git commit -m "Initial backend commit"

# Push to GitHub
gh repo create voxa-backend --public --source=. --remote=origin --push

Step 2: Deploy on Render

1. Go to render.com and sign in

2. Click "New +" → "Web Service"

3. Connect your GitHub repository

4. Select voxa-backend repo

5. Configure:

   • Name: voxa-backend
   • Region: Oregon (or closest to you)
   • Branch: main
   • Root Directory: Leave empty (or backend if it's in a subdirectory)
   • Environment: Node
   • Build Command: npm install
   • Start Command: npm start
   • Plan: Free

6. Add Environment Variables:

   • GEMINI_API_KEY: Your Gemini API key
   • API_SECRET: Generate a random secret (or let Render auto-generate)
   • NODE_ENV: production
   • RATE_LIMIT: 60
   • ALLOWED_ORIGINS: * (or your app domains)

7. Click "Create Web Service"

Step 3: Get Your Backend URL

Once deployed, Render will provide a URL like:

https://voxa-backend.onrender.com

Use this URL in your iOS app!

API Endpoints

POST /api/translate

Translate text between languages.

Request:

{
  "text": "Hello, how are you?",
  "sourceLanguage": "en",
  "targetLanguage": "ko",
  "tone": "neutral",
  "preserveNames": true
}

Response:

{
  "translation": "안녕하세요, 어떻게 지내세요?",
  "cached": false,
  "sourceLanguage": "en",
  "targetLanguage": "ko",
  "tone": "neutral"
}

Tone Options:

• casual: Conversational
• neutral: Professional (default)
• business_formal: Formal business

POST /api/translate/batch

Batch translate multiple texts (max 10).

Request:

{
  "texts": ["Hello", "Goodbye", "Thank you"],
  "sourceLanguage": "en",
  "targetLanguage": "ko",
  "tone": "neutral"
}

Response:

{
  "translations": [
    { "original": "Hello", "translation": "안녕하세요", "cached": false },
    { "original": "Goodbye", "translation": "안녕히 가세요", "cached": false },
    { "original": "Thank you", "translation": "감사합니다", "cached": false }
  ]
}

POST /api/tts

Generate speech from text.

Request:

{
  "text": "Hello, how are you?",
  "languageCode": "en-US",
  "voiceName": "Puck"
}

Response:

{
  "audio": "base64_encoded_mp3_data",
  "mimeType": "audio/mpeg",
  "cached": false
}

Voice Names:

• Puck: Natural, conversational
• Charon: Deep, authoritative
• Kore: Soft, pleasant
• Fenrir: Energetic
• Aoede: Warm, expressive

GET /api/tts/voices

List available voices.

Response:

{
  "voices": [
    { "name": "Puck", "language": "en", "characteristics": "Natural, conversational" },
    { "name": "Charon", "language": "en", "characteristics": "Deep, authoritative" }
  ]
}

POST /api/command

Parse voice command.

Request:

{
  "command": "switch to Japanese"
}

Response:

{
  "intent": "switch_language",
  "parameters": { "language": "ja" },
  "confidence": 0.95
}

Supported Intents:

• switch_language
• set_mode
• pause / resume
• repeat
• explain
• summarize

GET /health

Health check endpoint.

Response:

{
  "status": "ok",
  "timestamp": "2025-10-21T10:30:00.000Z",
  "uptime": 12345
}

Authentication

All /api/* endpoints require authentication:

Authorization: Bearer YOUR_API_SECRET

Set API_SECRET in environment variables.

Rate Limiting

• 60 requests per minute per IP (configurable)
• Returns 429 Too Many Requests when exceeded

Caching

• Translation results cached for 10 minutes
• TTS audio cached for 10 minutes
• Cache key includes all parameters
• Cached responses include "cached": true

Error Handling

All errors return JSON:

{
  "error": "Error message",
  "details": "Additional details",
  "timestamp": "2025-10-21T10:30:00.000Z"
}

Common Status Codes:

• 400: Bad request (missing parameters)
• 401: Unauthorized (invalid API key)
• 429: Rate limit exceeded
• 500: Server error

Monitoring

Logs

View logs on Render dashboard or via CLI:

# Install Render CLI
npm install -g render-cli

# View logs
render logs -s voxa-backend

Metrics

Monitor on Render dashboard:

• CPU usage
• Memory usage
• Request count
• Response times
• Error rates

Performance

Optimization Tips

1. Enable Caching: Results are cached automatically
2. Use Batch Endpoints: For multiple translations
3. Compress Responses: Enabled by default (gzip)
4. Connection Pooling: Axios handles this
5. Keep-Alive: Enabled by default

Expected Latency

• Translation: ~1-2 seconds
• TTS: ~2-4 seconds
• Command parsing: ~0.5-1 second
• Cached responses: <100ms

Security

Best Practices

1. API Secret: Use strong, random secret
2. CORS: Set specific allowed origins in production
3. Rate Limiting: Adjust based on your needs
4. HTTPS: Render provides free SSL
5. Environment Variables: Never commit .env file

Production Checklist

• Set strong API_SECRET
• Configure ALLOWED_ORIGINS (not *)
• Enable rate limiting
• Set up monitoring alerts
• Configure logging
• Test error handling

Scaling

Free Tier Limits (Render)

• Memory: 512 MB
• Instances: 1
• Sleep: After 15 minutes of inactivity
• Bandwidth: Unlimited

Upgrade Options

For production:

1. Starter Plan ($7/month):

   • No sleep
   • 512 MB RAM
   • Always on

2. Standard Plan ($25/month):

   • 2 GB RAM
   • Horizontal scaling
   • Priority support

Troubleshooting

Backend won't start

Check:

• Environment variables are set
• GEMINI_API_KEY is valid
• Port is not in use locally
• Dependencies installed (npm install)

TTS returns error

Check:

• Text length (<5000 chars)
• Gemini API key has TTS access
• Internet connection
• Rate limits not exceeded

High latency

Solutions:

• Enable caching (already enabled)
• Use batch endpoints
• Deploy to region closer to users
• Upgrade Render plan

Development

Project Structure

backend/
├── server.js           # Main server
├── routes/
│   ├── translation.js  # Translation endpoints
│   ├── tts.js          # TTS endpoints
│   └── command.js      # Command parsing
├── package.json        # Dependencies
├── .env.example        # Environment template
├── render.yaml         # Render config
└── README.md           # This file

Adding New Endpoints

1. Create route file in routes/
2. Import in server.js
3. Add middleware and validation
4. Update documentation

Testing

# Run tests (when implemented)
npm test

# Manual testing
npm run dev

# Use Postman or curl for API testing

Support

For issues:

1. Check logs on Render dashboard
2. Review Render docs
3. Check Gemini API status
4. Review this README

License

MIT

---

Last Updated: October 21, 2025