VoxVain docs
VoxVain is one API for text to speech, speech to text, turn detection, real-time voice agents and phone. Phone is generally available. Text to speech is specified in the OpenAPI document. Other products remain Preview placeholders unless marked Live.
Quickstart
Make your first audio file in two minutes.
API reference
Every endpoint, parameter and response.
Voice Agents
How sessions, tools and handoff work.
Product guides
Guides for each product are on their way. Each link below opens a placeholder until its guide is published.
Quickstart
Get an API key
See API keys below. Export it so the examples can read it:
export VOXVAIN_API_KEY="your-key-here"Make some speech
Send text and a voice id. The response is audio, not JSON.
Preview APIcurl -X POST https://api.voxvain.com/v1/text-to-speech/aria \ -H "Authorization: Bearer $VOXVAIN_API_KEY" \ -H "Content-Type: application/json" \ -d '{"text": "Hello from VoxVain.", "output_format": "mp3"}' \ --output hello.mp3import os import requests resp = requests.post( "https://api.voxvain.com/v1/text-to-speech/aria", headers={"Authorization": f"Bearer {os.environ['VOXVAIN_API_KEY']}"}, json={"text": "Hello from VoxVain.", "output_format": "mp3"}, timeout=60, ) resp.raise_for_status() with open("hello.mp3", "wb") as f: f.write(resp.content)import { writeFile } from "node:fs/promises"; const res = await fetch("https://api.voxvain.com/v1/text-to-speech/aria", { method: "POST", headers: { Authorization: `Bearer ${process.env.VOXVAIN_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ text: "Hello from VoxVain.", output_format: "mp3" }), }); if (!res.ok) throw new Error(`VoxVain API error ${res.status}: ${await res.text()}`); await writeFile("hello.mp3", Buffer.from(await res.arrayBuffer()));curl -X POST https://api.voxvain.com/v1/text-to-speech/aria/stream \ -H "Authorization: Bearer $VOXVAIN_API_KEY" \ -H "Content-Type: application/json" \ -d '{"text": "Hello from VoxVain.", "output_format": "mp3"}' \ --output hello.mp3import os import requests with requests.post( "https://api.voxvain.com/v1/text-to-speech/aria/stream", headers={"Authorization": f"Bearer {os.environ['VOXVAIN_API_KEY']}"}, json={"text": "Hello from VoxVain.", "output_format": "mp3"}, stream=True, timeout=60, ) as resp: resp.raise_for_status() with open("hello.mp3", "wb") as f: for chunk in resp.iter_content(chunk_size=None): f.write(chunk)import { createWriteStream } from "node:fs"; import { Readable } from "node:stream"; import { pipeline } from "node:stream/promises"; const res = await fetch("https://api.voxvain.com/v1/text-to-speech/aria/stream", { method: "POST", headers: { Authorization: `Bearer ${process.env.VOXVAIN_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ text: "Hello from VoxVain.", output_format: "mp3" }), }); if (!res.ok) throw new Error(`VoxVain API error ${res.status}: ${await res.text()}`); await pipeline(Readable.fromWeb(res.body), createWriteStream("hello.mp3"));List voices
GET /v1/voicesreturns the ids you can pass in that path. Usage for the key isGET /v1/usage.
API keys
Get a free API key with just your email. It is issued straight away, no card and no approval step. It is shown once, so copy it then. Upgrade to Pro or Scale on Pricing.
- Send the key as
Authorization: Bearer …on every request. - Keep it on your server. Never put it in browser or mobile code.
- Store it in the
VOXVAIN_API_KEYenvironment variable, not in source control.
SDKs
There is no VoxVain SDK package to install yet. Call the HTTPS API directly: the examples above use only curl, Python with requests (pip install requests), and JavaScript with the built-in fetch (Node 18 or later, saved as a .mjs file and run with node). Each request returns audio bytes.
Errors and limits
Errors return JSON: { "error": { "code": "invalid_request", "message": "…" } } with a 4xx or 5xx status. A 429 response includes Retry-After. Speech is $0.012 per 1,000 characters. GET /v1/usage reports characters, audio seconds and the customer charge.