Quickstart
Create an API key, generate speech, wait for the job and download the audio file.
This guide takes you from zero to an MP3 file. You need a Voiser account with credits and the admin or owner role.
Create an API key
In the studio, open Settings → API keys and create a key. Copy it right away: it is shown only once. Keys start with vs_.
Keep the key on your server, for example in an environment variable:
export VOISER_API_KEY="vs_..."Check that it works by reading your account and credit balance:
curl https://api.34.181.188.80.sslip.io/v2/account \
-H "Authorization: Bearer $VOISER_API_KEY"Pick a voice
List voices for a language and copy the id of one you like. Every voice has a short audio preview at GET/v2/voices/{voice_id}/preview.
curl "https://api.34.181.188.80.sslip.io/v2/voices?language=en&limit=5" \
-H "Authorization: Bearer $VOISER_API_KEY"{
"data": [
{
"id": "voice_8f2Kq1LmZx3T",
"name": "Ava",
"languages": ["en-US"],
"gender": "female",
"quality": "premium",
"styles": ["cheerful", "calm"]
}
],
"next_cursor": "50"
}Start a text to speech job
Send the text and the voice. The API answers 202 Accepted with a job, before the audio exists.
curl -X POST https://api.34.181.188.80.sslip.io/v2/text-to-speech \
-H "Authorization: Bearer $VOISER_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: quickstart-0001" \
-d '{
"text": "Welcome to Voiser. This audio was generated through the API.",
"voice_id": "voice_8f2Kq1LmZx3T"
}'{
"id": "0193a5b2-7c41-7d2e-9f3a-6b8c1d2e4f50",
"object": "job",
"operation": "text_to_speech",
"status": "queued",
"progress": 0,
"credits": { "estimated": 120, "charged": null },
"result": null,
"files": [],
"error": null,
"created_at": "2026-11-17T10:24:31.000Z",
"started_at": null,
"completed_at": null
}The Idempotency-Key header makes the request safe to retry: sending it again returns the same job instead of creating a second one. See Idempotency.
Wait for the job
Poll the job every couple of seconds until status is succeeded, failed or canceled. In production, pass webhook_url instead and let Voiser call you. See Webhooks.
curl https://api.34.181.188.80.sslip.io/v2/jobs/0193a5b2-7c41-7d2e-9f3a-6b8c1d2e4f50 \
-H "Authorization: Bearer $VOISER_API_KEY"{
"id": "0193a5b2-7c41-7d2e-9f3a-6b8c1d2e4f50",
"object": "job",
"operation": "text_to_speech",
"status": "succeeded",
"progress": 100,
"credits": { "estimated": 120, "charged": 96 },
"result": {
"file_id": "0193a5b3-1d0e-7a51-8c44-2f9b6e7d1a30",
"duration_ms": 4350,
"characters": 61
},
"files": [{ "id": "0193a5b3-1d0e-7a51-8c44-2f9b6e7d1a30", "role": "output", "index": 0 }],
"error": null,
"created_at": "2026-11-17T10:24:31.000Z",
"started_at": "2026-11-17T10:24:31.420Z",
"completed_at": "2026-11-17T10:24:34.910Z"
}Download the audio
Ask for the file to get a signed download_url. It is valid for 15 minutes; request the file again whenever you need a new link.
curl https://api.34.181.188.80.sslip.io/v2/files/0193a5b3-1d0e-7a51-8c44-2f9b6e7d1a30 \
-H "Authorization: Bearer $VOISER_API_KEY"
# then
curl -o speech.mp3 "<download_url from the response>"The whole flow in code
// Node.js 18+ (built-in fetch). Run as an ES module: node quickstart.mjs
import { writeFile } from "node:fs/promises";
const API = "https://api.34.181.188.80.sslip.io";
const KEY = process.env.VOISER_API_KEY;
async function api(path, { method = "GET", body, headers = {} } = {}) {
const res = await fetch(API + path, {
method,
headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json", ...headers },
body: body ? JSON.stringify(body) : undefined,
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message} (request ${data.error.request_id})`);
return data;
}
// 1. Start the job
let job = await api("/v2/text-to-speech", {
method: "POST",
headers: { "Idempotency-Key": crypto.randomUUID() },
body: { text: "Welcome to Voiser. This audio was generated through the API.", voice_id: "voice_8f2Kq1LmZx3T" },
});
// 2. Wait until it finishes
while (job.status === "queued" || job.status === "running") {
await new Promise((r) => setTimeout(r, 2000));
job = await api(`/v2/jobs/${job.id}`);
}
if (job.status !== "succeeded") throw new Error(`Job ${job.status}: ${job.error?.message}`);
// 3. Download the audio
const file = await api(`/v2/files/${job.result.file_id}`);
const audio = await fetch(file.download_url);
await writeFile("speech.mp3", Buffer.from(await audio.arrayBuffer()));
console.log(`Saved speech.mp3 (${job.credits.charged} credits)`);import os
import time
import uuid
import requests
API = "https://api.34.181.188.80.sslip.io"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['VOISER_API_KEY']}"
def api(method, path, **kwargs):
res = session.request(method, API + path, timeout=30, **kwargs)
data = res.json()
if not res.ok:
err = data["error"]
raise RuntimeError(f"{err['code']}: {err['message']} (request {err['request_id']})")
return data
# 1. Start the job
job = api(
"POST",
"/v2/text-to-speech",
headers={"Idempotency-Key": str(uuid.uuid4())},
json={"text": "Welcome to Voiser. This audio was generated through the API.", "voice_id": "voice_8f2Kq1LmZx3T"},
)
# 2. Wait until it finishes
while job["status"] in ("queued", "running"):
time.sleep(2)
job = api("GET", f"/v2/jobs/{job['id']}")
if job["status"] != "succeeded":
raise RuntimeError(f"Job {job['status']}: {job['error']}")
# 3. Download the audio
file = api("GET", f"/v2/files/{job['result']['file_id']}")
with open("speech.mp3", "wb") as f:
f.write(requests.get(file["download_url"], timeout=60).content)
print(f"Saved speech.mp3 ({job['credits']['charged']} credits)")<?php
// PHP 8+ with the curl extension.
const API = 'https://api.34.181.188.80.sslip.io';
function api(string $method, string $path, ?array $body = null, array $headers = []): array
{
$ch = curl_init(API . $path);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_HTTPHEADER => array_merge([
'Authorization: Bearer ' . getenv('VOISER_API_KEY'),
'Content-Type: application/json',
], $headers),
CURLOPT_POSTFIELDS => $body === null ? null : json_encode($body),
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) {
throw new RuntimeException("{$data['error']['code']}: {$data['error']['message']}");
}
return $data;
}
// 1. Start the job
$job = api('POST', '/v2/text-to-speech', [
'text' => 'Welcome to Voiser. This audio was generated through the API.',
'voice_id' => 'voice_8f2Kq1LmZx3T',
], ['Idempotency-Key: ' . bin2hex(random_bytes(16))]);
// 2. Wait until it finishes
while (in_array($job['status'], ['queued', 'running'], true)) {
sleep(2);
$job = api('GET', "/v2/jobs/{$job['id']}");
}
if ($job['status'] !== 'succeeded') {
throw new RuntimeException("Job {$job['status']}");
}
// 3. Download the audio
$file = api('GET', "/v2/files/{$job['result']['file_id']}");
file_put_contents('speech.mp3', file_get_contents($file['download_url']));
echo "Saved speech.mp3\n";