API reference
Base URL https://api.voxvain.com. Authenticate with Authorization: Bearer $VOXVAIN_API_KEY. This page is generated from the OpenAPI document (1.0.0).
GET/v1/healthPreview
Liveness
The service is up. status is disabled until the API is turned on.
Response
The service is up. status is disabled until the API is turned on.
GET/v1/voicesPreview
List voices
Voices this key can request.
Response
Voices this key can request.
POST/v1/text-to-speech/{voice_id}Preview
Create speech
Audio bytes. mp3 is audio/mpeg, wav is audio/wav, pcm is audio/L16 at 24000 Hz, mulaw_8000 is audio/basic at 8000 Hz.
| Field | Type | Description |
|---|---|---|
voice_id | string | A voice id from GET /v1/voices, such as aria. |
output_format | string | Optional. The JSON body field wins when both are set. |
text | string | Required. Text to speak. Every character counts, including spaces. |
output_format | string | mp3 (default), wav, pcm (16-bit little-endian, 24000 Hz, mono), or mulaw_8000 (8-bit mu-law, 8000 Hz, mono). |
Response
Audio bytes. mp3 is audio/mpeg, wav is audio/wav, pcm is audio/L16 at 24000 Hz, mulaw_8000 is audio/basic at 8000 Hz.
curl -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()));POST/v1/text-to-speech/{voice_id}/streamPreview
Stream speech
Same request as create speech. The body is chunked audio of the same format, so a client can start playback before the response ends.
| Field | Type | Description |
|---|---|---|
voice_id | string | A voice id from GET /v1/voices. |
text | string | Required. Text to speak. Every character counts, including spaces. |
output_format | string | mp3 (default), wav, pcm (16-bit little-endian, 24000 Hz, mono), or mulaw_8000 (8-bit mu-law, 8000 Hz, mono). |
Response
Chunked audio. Headers match create speech.
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"));GET/v1/usagePreview
Usage for this key
Characters and audio seconds recorded for this key. Text to speech is $0.012 per 1,000 characters (price_version 2026-10-03).
Response
Characters and audio seconds recorded for this key. Text to speech is $0.012 per 1,000 characters (price_version 2026-10-03).
GET/v1/clone/consent-agreementPreview
Voice cloning consent agreement
Draft wording, pending legal review. Before this API will create any cloned voice, your account must accept the current consent agreement once. You can do this in the customer portal or through the API. The response contains version, draft, info_panel, checkboxes (id, text), terms_url and text_sha256, plus accepted and accepted_at for your key.
POST/v1/clone/consent-agreement/accept
Body: {"version": "<current version>", "checkboxes": {"permission": true, "responsibility": true, "no_deception": true}}. All three must be true. We log the account, time, IP address and agreement version. When the version changes, you must accept it again.
Clone requests
POST /v1/voices/clone requires a customer_reference (an X-Customer-Reference header or query parameter; 1–128 characters from A-Z a-z 0-9 . _ : @ / -). It identifies the consenting voice owner in your own records and is stored with the clone, along with the time and the agreement version.
Errors
403 consent_agreement_required: the current agreement has not been accepted for this key.400 consent_checkbox_required: one or more checkboxes were not ticked.409 consent_agreement_version_mismatch: you accepted an outdated version.400 customer_reference_required: the reference is missing or invalid.