Build production-ready voice experiences with CodeVoice

Introduction

CodeVoice is a text-to-speech platform for generating natural voice output through a clean dashboard and API workflow. It combines an interactive UI for testing and account management with programmatic access for application integration.

The platform is built around three core capabilities: generating speech from text, discovering available voices and languages, and tracking account-level credit consumption. That makes it suitable both for fast prototyping and for embedding speech generation into production products.

Getting Started

Use the following sequence to go from account creation to your first generated audio response.

Authentication

All authenticated API requests should include your API key in the request headers. Treat this key like a secret and never expose it in public client code unless your architecture explicitly allows it.

X-API-Key: YOUR_API_KEY
Authorization: Bearer YOUR_JWT_TOKEN

Developer API calls usually use X-API-Key. Logged-in dashboard users can also call protected routes with a JWT bearer token from /api/auth/login.

For frontend integrations, prefer routing requests through your own secure backend or edge layer when you need stronger control over exposure, rate limiting, or user-level enforcement.

Text to Speech API

The primary speech endpoint is POST /v1/tts. It queues a generation job and returns a job_id that you then poll through the status endpoint until the audio file is ready.

Queue a job

POST /v1/tts
Content-Type: application/json
X-API-Key: YOUR_API_KEY

{
  "text": "Hello world from CodeVoice",
  "voice": "ryan"
}

Queue response

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "user_type": "registered",
  "tier": 1,
  "message": "Free credit used. 59 remaining."
}

curl -X POST http://127.0.0.1:8000/v1/tts \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d "{\"text\":\"Hello world from CodeVoice\",\"voice\":\"ryan\"}"

Speech Job Flow

CodeVoice TTS is asynchronous. After queueing a job, poll the status endpoint until the job is completed, then download or stream the audio from the returned path.

GET /tts/status/550e8400-e29b-41d4-a716-446655440000

{
  "status": "completed",
  "audio_url": "/tts/audio/550e8400-e29b-41d4-a716-446655440000"
}

curl -L http://127.0.0.1:8000/tts/audio/550e8400-e29b-41d4-a716-446655440000 --output voice.wav

Voices API

The voices endpoint is used to discover the list of voices available to your account and identify which voices support the languages or quality levels your product requires.

GET /v1/voices

{
  "voices": [
    {
      "name": "ryan",
      "gender": "male",
      "language": "en-US",
      "language_name": "English",
      "description": "Voice: ryan",
      "quality": "high"
    }
  ]
}

Speech to Text API

CodeVoice also exposes STT utilities for language discovery, uploaded file transcription, and live-browser completion accounting.

curl -X POST http://127.0.0.1:8000/transcribe \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "language=en-US" \
  -F "file=@sample.wav"

Account API

The dashboard and auth experience use JWT-based account endpoints. These are useful when you want your product to create accounts, log users in, and surface dashboard usage information in-app.

POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your-password"
}

Credits System

CodeVoice uses a credit-based model to track usage. For registered users, one successful generation or billed STT completion consumes one credit. The dashboard separates free monthly credits from paid credits so you can see how usage is allocated over time.

• 1 request equals 1 credit.
• Registered users receive monthly free credits that reset each month.
• Paid credits are used when free monthly allocation is exhausted.
• API-only users can be configured by admins with monthly limits, extra credits, or unlimited mode.
• Usage statistics in the dashboard help you monitor requests, success rate, and recent activity.

Error Handling

When a request cannot be completed, the API returns an error response that should be surfaced clearly in your application. Build your integration so it distinguishes between auth failures, validation problems, and account usage issues.

{
  "detail": {
    "error": "insufficient_credits",
    "message": "Monthly API credit limit reached. Please contact admin or enable unlimited access.",
    "user_type": "api_only"
  }
}

SDK / Integration

You can integrate CodeVoice in any frontend or backend stack using standard HTTP requests. The examples below show the recommended server-side proxy pattern, a direct backend Python client, and a frontend polling flow for completed TTS jobs.

Node / backend proxy

app.post("/api/tts", async (req, res) => {
  const response = await fetch("http://127.0.0.1:8000/v1/tts", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": process.env.CODEVOICE_API_KEY
    },
    body: JSON.stringify({
      text: req.body.text,
      voice: req.body.voice || "ryan"
    })
  });

  const data = await response.json();
  res.status(response.status).json(data);
});

Frontend polling example

const queued = await fetch("/api/tts", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    text: "Hello from the browser",
    voice: "ryan"
  })
}).then(res => res.json());

const poll = async (jobId) => {
  while (true) {
    const status = await fetch(`/tts/status/${jobId}`).then(res => res.json());
    if (status.status === "completed") return status.audio_url;
    if (status.status === "failed") throw new Error(status.error || "TTS failed");
    await new Promise(resolve => setTimeout(resolve, 1500));
  }
};

Python integration

import requests
import time

BASE_URL = "http://127.0.0.1:8000"
HEADERS = {"X-API-Key": "YOUR_API_KEY"}

job = requests.post(
    f"{BASE_URL}/v1/tts",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={"text": "Hello from Python", "voice": "ryan"},
).json()

job_id = job["job_id"]
while True:
    status = requests.get(f"{BASE_URL}/tts/status/{job_id}").json()
    if status["status"] == "completed":
        audio = requests.get(f"{BASE_URL}{status['audio_url']}")
        open("voice.wav", "wb").write(audio.content)
        break
    if status["status"] == "failed":
        raise RuntimeError(status.get("error", "TTS failed"))
    time.sleep(1.5)

For larger apps, wrap request calls in a dedicated API client layer so auth headers, retries, and response parsing stay consistent across your codebase.

FAQ