Getting started

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"
Response (shortened)
{
  "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"
  }'
202 Accepted
{
  "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"
200 OK
{
  "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)`);

Next steps