API Reference

lvox auth login YOUR_API_KEY

Saves your API key to ~/.lvox/config.toml. Or set LEANVOX_API_KEY env var.

# Stream audio (writes chunks as they arrive)
lvox stream "Hello world!" -o hello.mp3

# List voices
lvox voices list
lvox voices list --model pro

# Check balance
lvox balance

# View usage history
lvox usage --days 7

# List past generations
lvox history
lvox history audio <id> -o replay.mp3

# JSON output (all commands)
lvox balance --json

Authorization: Bearer lv_live_YOUR_API_KEY

{ "email": "[email protected]", "password": "your-password" }

{ "email": "[email protected]", "password": "your-password" }

Returns: { "token": "jwt...", "user": { "id", "email" } }

{
  "text": "Hello world!",
  "model": "standard",     // "standard" or "pro"
  "voice": "af_heart",     // voice ID
  "language": "en",        // ISO 639-1 code
  "format": "mp3",         // optional: "mp3" (default) or "wav"
  "speed": 1.0,            // optional: 0.5 - 2.0
  "exaggeration": 0.5      // optional (pro only): 0.0 - 1.0
}

{
  "audio_url": "https://cdn.leanvox.com/audio/abc123.mp3",
  "model": "standard",
  "voice": "af_heart",
  "characters": 12,
  "cost_cents": 0.06
}

{
  "text": "Hello world!",
  "model": "standard",     // "standard" or "pro"
  "voice": "af_heart",     // voice ID
  "language": "en",        // ISO 639-1 code
  "exaggeration": 0.5      // optional (pro only): 0.0 - 1.0
}

Same request body as /v1/tts/generate. Always returns MP3 format.

curl -N -X POST https://api.leanvox.com/v1/tts/stream \
  -H "Authorization: Bearer lv_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world!", "model": "standard", "voice": "af_heart"}' \
  --output speech.mp3

const res = await fetch("https://api.leanvox.com/v1/tts/stream", {
  method: "POST",
  headers: {
    "Authorization": "Bearer lv_live_YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ text: "Hello world!", model: "standard" }),
});

// Pipe to audio element via MediaSource API or save as blob
const blob = await res.blob();
const audioUrl = URL.createObjectURL(blob);

{
  "model": "pro",
  "lines": [
    { "text": "Hi there!", "voice": "emma", "language": "en" },
    { "text": "Hello! [laugh]", "voice": "james", "language": "en", "exaggeration": 0.7 }
  ],
  "gap_ms": 500    // silence between lines (default 500)
}

Multipart form upload. Auth required. Max 5 MB. Returns up to 500,000 characters.

// Request: multipart/form-data with field "file"
// Accepted types: .txt, .epub

// Response
{
  "text": "Chapter 1. It was a dark and stormy night...",
  "filename": "my-book.epub",
  "char_count": 142830,
  "truncated": false   // true if file exceeded 500K chars
}

Returns 14 curated AI-designed Pro voices with preview audio URLs.

{
  "name": "My Voice",
  "audio_base64": "<base64-encoded WAV>",
  "description": "optional description"
}

Upload a 5-30 second WAV clip. Returns a voice_id for use with the Pro model.

Unlock a cloned voice for TTS use. Costs $3.00 per voice.

{
  "name": "Deep Narrator",
  "description": "A deep, warm male voice for audiobooks",
  "language": "en",
  "notes": "optional extra guidance"
}

AI-generates a custom voice from a text description. Costs $1.00 per voice.

{
  "generations": [
    {
      "id": "uuid",
      "generation_type": "tts",
      "input_text": "Hello world!",
      "model": "standard",
      "voice": "af_heart",
      "format": "mp3",
      "characters": 12,
      "cost_cents": 1,
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

{ "audio_url": "https://cdn.leanvox.com/audio/abc123.mp3?token=..." }

Returns a presigned URL valid for 1 hour.

Permanently deletes the generation and its audio file from storage.

Same body as /v1/tts/generate. Optional "webhook_url" for completion callback.

{
  "id": "uuid",
  "status": "pending" | "processing" | "completed" | "failed",
  "audio_url": "...",      // when completed
  "error": "...",          // when failed
  "created_at": "..."
}

{ "balance_cents": 450, "total_spent_cents": 50 }

{ "amount_cents": 2000 }

Returns a Stripe checkout URL. Tiers: $5 (0%), $20 (+10%), $50 (+15%), $100 (+20% bonus).

pip install leanvox

result = client.generate(
    text="Welcome to the future of voice.",
    model="pro",         # "standard" or "pro"
    voice="emma",
    language="en",
    speed=1.0,
    exaggeration=0.5,    # pro only: 0.0 - 1.0
)
result.save("welcome.mp3")

with client.stream(text="A long narration about the universe...") as stream:
    with open("narration.mp3", "wb") as f:
        for chunk in stream:
            f.write(chunk)

Streaming always outputs MP3.

result = client.dialogue(
    model="pro",
    lines=[
        {"text": "Welcome to the podcast!", "voice": "emma"},
        {"text": "Thanks for having me.", "voice": "james"},
        {"text": "Let's dive right in.", "voice": "emma"},
    ],
    gap_ms=400,
)
result.save("podcast.mp3")

# Priority: constructor → env var → config file
client = Leanvox(api_key="lv_live_...")       # 1. Explicit
# export LEANVOX_API_KEY="lv_live_..."        # 2. Env var
# ~/.lvox/config.toml                         # 3. Config file

from leanvox import (
    Leanvox,
    InsufficientBalanceError,
    RateLimitError,
    LeanvoxError,
)

try:
    result = client.generate(text="Hello!")
except InsufficientBalanceError as e:
    print(f"Low balance: ${e.balance_cents / 100:.2f}")
except RateLimitError as e:
    print(f"Retry after {e.retry_after}s")
except LeanvoxError as e:
    print(f"API error [{e.code}]: {e.message}")

npm install leanvox

import { Leanvox } from "leanvox";

const client = new Leanvox();  // uses LEANVOX_API_KEY env var

const result = await client.generate({ text: "Hello from Leanvox!" });
console.log(result.audioUrl);

// Save directly to file
await result.save("hello.mp3");

const result = await client.generate({
  text: "Welcome to the future of voice.",
  model: "pro",         // "standard" or "pro"
  voice: "emma",
  language: "en",
  speed: 1.0,
  exaggeration: 0.5,    // pro only: 0.0 - 1.0
});
await result.save("welcome.mp3");

import { createWriteStream } from "fs";

const stream = await client.stream({
  text: "A long narration about the universe...",
  voice: "af_heart",
});

const writer = createWriteStream("narration.mp3");
for await (const chunk of stream) {
  writer.write(chunk);
}
writer.end();

Streaming always outputs MP3.

const result = await client.dialogue({
  model: "pro",
  lines: [
    { text: "Welcome to the podcast!", voice: "emma" },
    { text: "Thanks for having me.", voice: "james" },
    { text: "Let's dive right in.", voice: "emma" },
  ],
  gapMs: 400,
});
await result.save("podcast.mp3");

// Priority: constructor → env var → config file
const client = new Leanvox({ apiKey: "lv_live_..." }); // 1. Explicit
// export LEANVOX_API_KEY="lv_live_..."                 // 2. Env var
// ~/.lvox/config.toml                                  // 3. Config file

import {
  Leanvox,
  InsufficientBalanceError,
  RateLimitError,
  LeanvoxError,
} from "leanvox";

try {
  const result = await client.generate({ text: "Hello!" });
} catch (e) {
  if (e instanceof InsufficientBalanceError) {
    console.log(`Low balance: $${(e.balanceCents / 100).toFixed(2)}`);
  } else if (e instanceof RateLimitError) {
    console.log(`Retry after ${e.retryAfter}s`);
  } else if (e instanceof LeanvoxError) {
    console.log(`API error [${e.code}]: ${e.message}`);
  }
}

npx @leanvox/mcp-server

Or install globally: npm install -g @leanvox/mcp-server

{
  "mcpServers": {
    "leanvox": {
      "command": "npx",
      "args": ["-y", "@leanvox/mcp-server"],
      "env": {
        "LEANVOX_API_KEY": "lv_live_your_key_here"
      }
    }
  }
}

{
  "leanvox": {
    "command": "npx",
    "args": ["-y", "@leanvox/mcp-server"],
    "env": {
      "LEANVOX_API_KEY": "lv_live_your_key_here"
    }
  }
}

{
  "servers": {
    "leanvox": {
      "command": "npx",
      "args": ["-y", "@leanvox/mcp-server"],
      "env": {
        "LEANVOX_API_KEY": "lv_live_your_key_here"
      }
    }
  }
}

{
  "type": "function",
  "function": {
    "name": "leanvox_generate",
    "description": "Generate speech audio from text using Leanvox TTS API. Returns a URL to the generated audio file.",
    "strict": true,
    "parameters": {
      "type": "object",
      "properties": {
        "text": {
          "type": "string",
          "description": "Text to convert to speech (max 10,000 chars)"
        },
        "model": {
          "type": "string",
          "enum": ["standard", "pro"],
          "description": "TTS model. 'standard' for fast/cheap, 'pro' for highest quality with emotion control"
        },
        "voice": {
          "type": "string",
          "description": "Voice ID (e.g. 'af_heart', 'emma', 'james'). Use leanvox_list_voices to see options."
        },
        "language": {
          "type": "string",
          "description": "ISO 639-1 language code (default: 'en')"
        },
        "speed": {
          "type": "number",
          "description": "Playback speed 0.5-2.0 (default: 1.0)"
        }
      },
      "required": ["text"],
      "additionalProperties": false
    }
  }
}

{
  "name": "leanvox_generate",
  "description": "Generate speech audio from text using Leanvox TTS API. Returns a URL to the generated audio file.",
  "input_schema": {
    "type": "object",
    "properties": {
      "text": {
        "type": "string",
        "description": "Text to convert to speech (max 10,000 chars)"
      },
      "model": {
        "type": "string",
        "enum": ["standard", "pro"],
        "description": "TTS model. 'standard' for fast/cheap, 'pro' for highest quality with emotion control"
      },
      "voice": {
        "type": "string",
        "description": "Voice ID (e.g. 'af_heart', 'emma', 'james'). Use leanvox_list_voices to see options."
      },
      "language": {
        "type": "string",
        "description": "ISO 639-1 language code (default: 'en')"
      },
      "speed": {
        "type": "number",
        "description": "Playback speed 0.5-2.0 (default: 1.0)"
      }
    },
    "required": ["text"]
  }
}