Frontend Guide

Frontend Developer Guide

Integration guide for frontend builders. The intended product experience is a paid voice API with browser-friendly preview workflows, account usage controls, and server-safe API key handling.

Recommended Frontend Model

Customer signs in to your product

Your backend maps the customer to an API account, balance, and token quota

Browser calls your backend or a signed proxy endpoint

Your backend calls the public Voice API

Usage is metered and reflected back in your product UI

Key Endpoints to Integrate First

POST /voices/previewPOST /voices/preview/streamPOST /voices/analyzePOST /voices/validateGET /voices/{voice_id}

Browser vs Server Responsibility

Browser Should Handle

Upload selection and mic recording UX
Preview player UI
Progress and loading states
Usage display and remaining balance
Retry and validation messaging

Backend Should Handle

Raw API key storage
Customer billing state
Token deduction and reconciliation
Rate limiting per customer or workspace
Proxying signed requests to the voice API

Recommended Browser UX

Core Screens

Screen	Purpose
Voice list	Show available voice IDs and labels
Text preview composer	Enter text for preview or stream
Live player	Play streamed preview audio
Usage panel	Show token estimate, cost, and remaining balance
History panel	Show prior previews and validation results
Billing state	Show insufficient-balance and upgrade state

Recommended Flow

User selects voice

User enters preview text

Frontend asks backend for a token estimate

Frontend shows estimated token cost before generation

User confirms preview request

Backend forwards to Voice API

Frontend plays stream or receives preview payload

Frontend updates usage UI from backend-confirmed balance state

Browser Integration Patterns

Pattern A

JSON Preview

Use when you need waveform analysis, metadata display, easier persistence, or simpler debugging.

async function requestPreview( baseUrl: string, apiKey: string, voiceId: string, text: string ) { const response = await fetch(`${baseUrl}/voices/preview`, { method: "POST", headers: { "Content-Type": "application/json", "X-API-Key": apiKey, }, body: JSON.stringify({ voice_id: voiceId, text, include_audio_base64: true, persist_preview: true, }), }); if (!response.ok) { throw new Error(await response.text()); } return response.json(); }

Pattern B

Realtime Stream

Use when you need immediate playback, lower-latency preview UX, or simpler audio-only delivery.

async function streamPreview( baseUrl: string, apiKey: string, voiceId: string, text: string ) { const response = await fetch(`${baseUrl}/voices/preview/stream`, { method: "POST", headers: { "Content-Type": "application/json", "X-API-Key": apiKey, }, body: JSON.stringify({ voice_id: voiceId, text, }), }); if (!response.ok || !response.body) { throw new Error(await response.text()); } return response.body; }

Product States

Your frontend should explicitly handle these states:

State	Meaning
idle	No request in flight
estimating	Waiting for token estimate
streaming	Receiving realtime audio
completed	Request finished successfully
insufficient-balance	Account cannot generate
invalid-input	Request text or voice config invalid
rate-limited	Account exceeded allowed burst or throughput
service-unavailable	Backend or voice runtime unavailable

Best Practices

Show estimated token usage before confirming generation
Show actual consumed usage after completion
Surface rate-limit and insufficient-balance states clearly
Separate preview usage from production usage
Keep replay and history actions visible

Avoid

Embedding permanent API keys in browser bundles
Charging based only on client-side estimates
Assuming all preview routes return JSON
Treating internal admin routes as public APIs
Storing balance truth only in frontend state

Pricing, Tokens & Usage

Voice API Endpoints