REST API

Base URL: https://api.lokutor.com. Every route also answers under a /v1/ prefix (/v1/tts/synthesize is the same endpoint as /tts/synthesize).

Method	Path	Key	What it does
`POST`	`/tts/synthesize`	Yes	Text to a WAV file
`POST`	`/stt/transcribe`	Yes	A recorded clip to text
`POST`	`/denoise`	Yes	Remove background noise from a WAV file
`POST`	`/ws-ticket`	Yes	Exchange your key for a 10-minute ticket
`GET`	`/voices`, `/languages`, `/models`, `/config`, `/status`, `/v1/pricing`, `/ready`	No	Discovery

Authenticated endpoints accept Authorization: Bearer <key>, X-API-Key: <key> or ?api_key=<key>, with an API key or a wst_ ticket (Authentication). Streaming synthesis and live transcription run over WebSocket: see Real-time Streaming and Speech-to-Text. Phone numbers and calls are in the Call Center API. Errors use the structured shape in the Error Catalog, except where noted below.

`POST /tts/synthesize` — TTS Synthesis

Synthesizes text and returns the whole clip as a WAV file. Billed per character from your balance (rate card: tts_per_million_chars).

Request

{
  "text": "Hello, world!",
  "voice": "F1",
  "language": "en"
}

Parameter	Type	Required	Default	Description
`text`	`string`	Yes, unless `segments` is given	—	Text to synthesize.
`voice`	`string`	Yes	—	Voice slot (`F1`–`F5`, `M1`–`M5`) or one of your `clone_…` ids. Unknown ids answer `400` `validation.invalid_voice`. See Voices.
`language`	`string`	No	none	ISO code from `GET /languages`. Unknown codes answer `400` `validation.invalid_language`. Without it, synthesis has no language hint and the slot resolves to the English speaker; pass it for predictable results.
`segments`	`array`	No	—	Several voices or languages in one clip (below). When present, top-level `text` is ignored, though still counted toward the character limit.
`steps`	`int`	No	—	`1`–`8`; a higher value is treated as `8`, without an error. Accepted for compatibility; no effect on versa-2.0.
`cfg`	`number`	No	—	`1`–`4`. Accepted for compatibility; no effect on versa-2.0.
`cfg_text`	`number`	No	—	`1`–`10`. Accepted for compatibility; no effect on versa-2.0.
`speed`	`number`	No	`1.0`	A value outside 0.5–2.0 is reset to `1.0`. Accepted for compatibility; no effect on versa-2.0.
`pronunciation_dictionary_ids`	`string[]`	No	—	Pronunciation dictionaries to apply, on top of your default one. See Pronunciation.
`pronunciations`	`array`	No	—	Pronunciation entries for this request only (`{term, say_as: {lang: respelling}}`); they win over every dictionary. A malformed entry answers `400` `validation.invalid_request_format`.
`temperature`	`number`	No	`0.3`	How varied the delivery is, `0.1`–`1.0`; higher sounds livelier and less predictable. Outside the range answers `400` `validation.invalid_request_format`.

Each entry in segments is either speech, { "text", "voice"?, "language"? } (falling back to the top-level voice and language), or a pause, { "pause_ms": 500 }. Every segment’s voice and language are validated before any audio is produced, so a bad value in the last segment fails the request without synthesizing the others.

{
  "voice": "F1",
  "language": "en",
  "segments": [
    { "text": "Welcome to the show." },
    { "pause_ms": 400 },
    { "text": "Bienvenidos al programa.", "voice": "M2", "language": "es" }
  ]
}

The older names voice_id, lang and quality are accepted as aliases. quality is ignored. New code should use voice and language.

Limits

Limit	Value	Over the limit
Characters, counted across `text` and every segment	5,000	`400` `validation.text_too_long`
Segments	200	`400` `validation.text_too_long`
`pause_ms` per pause	0–10,000	`400` `validation.text_too_long`
Pauses in total	60,000 ms	`400` `validation.text_too_long`
Request body	1 MB	`400` `validation.invalid_request_format`

Characters are counted as characters, not bytes: an accented letter is one.

Response

200, Content-Type: audio/wav: 16-bit PCM, 44.1 kHz, mono.

Status	Body	When
`400`	Error catalog shape	`validation.invalid_request_format` (bad JSON, missing `text` or `voice`), `validation.invalid_voice`, `validation.invalid_language`, `validation.text_too_long`
`401`	Error catalog shape	`auth.missing_key`, `auth.invalid_key`
`402`	Error catalog shape	`billing.insufficient_balance`, `billing.account_disputed`, `billing.limit_reached` (Billing errors)
`503`	`{"error", "voice", "hint"}` with a `Retry-After` header	The synthesis pool is at capacity or not answering. Retry after the number of seconds in `Retry-After`.

The 503 body is not the error-catalog shape:

{
  "error": "synthesis capacity reached, retry shortly",
  "voice": "F1",
  "hint": "every stream slot on this worker is in use; the request was not malformed"
}

cURL

curl -X POST https://api.lokutor.com/tts/synthesize \
  -H "Authorization: Bearer $LOKUTOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world", "voice": "F1", "language": "en"}' \
  --output hello.wav

`POST /stt/transcribe` — Speech-to-Text

Transcribes one complete audio clip. For live transcription from a microphone, use WS /ws/stt (Speech-to-Text). Recognition covers English, Spanish, Catalan, Galician, Basque, Portuguese, French, Italian and German, with one model for all nine. The text comes back written out: digits, phone numbers, e-mail addresses, punctuation and casing. Billed per minute of audio (rate card: stt_per_minute).

Request

Send either multipart/form-data with the file in a field named audio (plus optional language and keyterms), or JSON with base64 audio:

{
  "audio": "<base64-encoded WAV or PCM16>",
  "format": "wav",
  "language": "en"
}

Parameter	Type	Default	Description
`audio`	`string`	—	Base64 audio (JSON only; use the `audio` form field for multipart)
`format`	`string`	`"wav"`	`"wav"`, or `"pcm16"` for raw 16-bit little-endian mono samples
`sample_rate`	`int`	`16000`	Required for `"pcm16"`; read from the header for WAV
`language`	`string`	detected	One of `en`, `es`, `ca`, `gl`, `eu`, `pt`, `fr`, `it`, `de`. Send it whenever you know it: it makes one-word replies (“sí”, “no”) reliable and keeps the transcript in that language. Without it the language is detected from the clip.
`keyterms`	`string[]` or `string`	—	Custom vocabulary: names, brands and terms to write your way when what is heard is close (a list, or one comma-separated string; a form field takes the comma-separated form). Up to 100 terms of 40 characters; more answers `400` `validation.invalid_request_format`. See Custom vocabulary.

Accepted audio: WAV with 8- or 16-bit PCM, mono or stereo, at 8000, 11025, 12000, 16000, 22050, 24000, 32000, 44100 or 48000 Hz, up to 10 MB. Anything else answers 400 validation.invalid_request_format. This API’s own TTS output (44.1 kHz WAV) is accepted as is.

Response

{
  "text": "Hello, this is a test.",
  "latency_ms": 240,
  "engine": "lokutor-stt",
  "sample_rate": 16000,
  "language": "en",
  "duration_seconds": 2.1,
  "segments": [
    { "text": "Hello, this is a test.", "start": 0.0, "end": 2.1, "duration": 2.1 }
  ]
}

cURL

curl -X POST https://api.lokutor.com/stt/transcribe \
  -H "Authorization: Bearer $LOKUTOR_API_KEY" \
  -F "[email protected]" \
  -F "language=en"

`POST /denoise` — Audio Denoising

Removes background noise from a WAV file with Psst, the same model that cleans callers’ audio on agent calls. Billed per minute of audio (rate card: denoise_per_minute).

Request

multipart/form-data with the WAV file in a field named audio. The same formats and the same 10 MB limit as /stt/transcribe apply; anything else answers 400 validation.invalid_request_format. If the denoiser is unavailable or fails, the answer is 503 agent.provider_error.

curl -X POST https://api.lokutor.com/denoise \
  -H "Authorization: Bearer $LOKUTOR_API_KEY" \
  -F "[email protected]" \
  --output clean.wav

Response

200, Content-Type: audio/wav: the denoised audio, 16-bit PCM.

`POST /ws-ticket` — Short-lived Ticket

Exchanges your API key, sent in the Authorization or X-API-Key header (never the URL), for a ticket that works anywhere a key does for 10 minutes. Use it to keep the key out of browsers. See Authentication and Secure browser setup.

curl -X POST https://api.lokutor.com/ws-ticket -H "Authorization: Bearer $LOKUTOR_API_KEY"

{ "ticket": "wst_…", "expires_in": 600 }

Discovery

These endpoints need no key.

`GET /voices` — List Voice Styles

{
  "model": "versa-2.0",
  "voices": [
    { "id": "F1", "name": "Claire", "gender": "female", "languages": ["en", "es", "ca", "gl", "eu", "pt", "fr", "it", "de"] },
    { "id": "M1", "name": "James", "gender": "male", "languages": ["en", "es", "ca", "gl", "eu", "pt", "fr", "it", "de"] }
  ]
}

Field	Type	Description
`model`	`string`	The synthesis model serving these voices
`voices[].id`	`string`	Voice slot, e.g. `F1`, `M3`
`voices[].name`	`string`	The slot’s display name. The speaker heard depends on `language`: each language has its own speaker in each slot (Voices).
`voices[].gender`	`string`	`"female"` or `"male"`
`voices[].languages`	`string[]`	Languages the slot can speak: all nine

GET /voices lists the built-in slots only. Your cloned voices are listed in the dashboard under Voices, each with its clone_… id; any endpoint that takes a voice accepts one only from an API key on the account that created it, and answers validation.invalid_voice from any other account.

`GET /languages` — List Supported Languages

Every language text-to-speech can speak. Speech recognition covers all nine.

{
  "languages": [
    { "code": "en", "name": "English" },
    { "code": "es", "name": "Spanish" },
    { "code": "ca", "name": "Catalan" },
    { "code": "gl", "name": "Galician" },
    { "code": "eu", "name": "Basque" },
    { "code": "pt", "name": "Portuguese" },
    { "code": "fr", "name": "French" },
    { "code": "it", "name": "Italian" },
    { "code": "de", "name": "German" }
  ]
}

`GET /models` — List TTS Models

{
  "models": [
    { "name": "versa-2.0", "description": "Primary production model", "default": true }
  ]
}

versa-2.0 is the only model served.

`GET /config` — Server Configuration

{
  "max_text_length": 5000,
  "min_speed": 0.5,
  "max_speed": 2.0,
  "min_steps": 1,
  "max_steps": 8,
  "sample_rate": 44100,
  "channels": 1
}

Field	Description
`max_text_length`	Maximum characters per synthesis request
`min_speed`, `max_speed`	The range `/ws/tts` accepts for `speed` without an error
`min_steps`, `max_steps`	The highest `steps` synthesis honours: `POST /tts/synthesize` treats anything above `8` as `8` (`/ws/tts` still accepts up to `128` without an error). Neither parameter changes the audio on `versa-2.0` (Parameters).
`sample_rate`, `channels`	Output audio format: 44,100 Hz, mono

`GET /status` — Runtime Status

{
  "status": "ok",
  "timestamp": "2026-10-18T16:31:23.955Z",
  "version": "1.1.0",
  "runtime": "go1.24.10",
  "inference": "cpu",
  "uptime_seconds": 17,
  "goroutines": 61,
  "mem_alloc_bytes": 73432552,
  "active_connections": 0,
  "failed_requests": 0,
  "ready": true
}

status is "ok" or "warming_up", and ready says whether the server can serve. The other fields describe the one API server that answered and are informational; inference is an internal label and does not say where synthesis runs.

`GET /v1/pricing` — Rate Card

Every price Lokutor charges, as JSON. Fields and an example are on the Rate Card page; how the prices apply is in Pricing and billing.

`GET /ready` — Readiness

200 {"ready": true, "status": "ready"} once the server can serve requests; 503 {"ready": false, "status": "not_ready"} while it is starting. Use it for uptime checks.

JavaScript SDK

The SDK wraps the discovery endpoints as static methods on VoiceAgentClient. They call https://api.lokutor.com and throw LokutorError on failure.

import { VoiceAgentClient } from '@lokutor/sdk';

const voices = await VoiceAgentClient.fetchVoices();     // GET /voices
const languages = await VoiceAgentClient.fetchLanguages(); // GET /languages
const models = await VoiceAgentClient.fetchModels();     // GET /models
const config = await VoiceAgentClient.fetchConfig();     // GET /config
const status = await VoiceAgentClient.fetchStatus();     // GET /status
const ready = await VoiceAgentClient.fetchHealth();      // GET /ready

cURL Examples

curl -s https://api.lokutor.com/ready
curl -s https://api.lokutor.com/voices
curl -s https://api.lokutor.com/languages
curl -s https://api.lokutor.com/config
curl -s https://api.lokutor.com/v1/pricing

Real-time Streaming: TTS over WebSocket
Voice Chat and WebSocket Protocol: the voice agent
Error Catalog
OpenAPI Spec

Get Started

SDK

API Reference

Resources

`POST /tts/synthesize` — TTS Synthesis

Request

Limits

Response

cURL

`POST /stt/transcribe` — Speech-to-Text

Request

Response

cURL

`POST /denoise` — Audio Denoising

Request

Response

`POST /ws-ticket` — Short-lived Ticket

Discovery

`GET /voices` — List Voice Styles

`GET /languages` — List Supported Languages

`GET /models` — List TTS Models

`GET /config` — Server Configuration

`GET /status` — Runtime Status

`GET /v1/pricing` — Rate Card

`GET /ready` — Readiness

JavaScript SDK

cURL Examples

​POST /tts/synthesize — TTS Synthesis

​Request

​Limits

​Response

​cURL

​POST /stt/transcribe — Speech-to-Text

​Request

​Response

​cURL

​POST /denoise — Audio Denoising

​Request

​Response

​POST /ws-ticket — Short-lived Ticket

​Discovery

​GET /voices — List Voice Styles

​GET /languages — List Supported Languages

​GET /models — List TTS Models

​GET /config — Server Configuration

​GET /status — Runtime Status

​GET /v1/pricing — Rate Card

​GET /ready — Readiness

​JavaScript SDK

​cURL Examples

​Related Pages

`POST /tts/synthesize` — TTS Synthesis

Request

Limits

Response

cURL

`POST /stt/transcribe` — Speech-to-Text

Request

Response

cURL

`POST /denoise` — Audio Denoising

Request

Response

`POST /ws-ticket` — Short-lived Ticket

Discovery

`GET /voices` — List Voice Styles

`GET /languages` — List Supported Languages

`GET /models` — List TTS Models

`GET /config` — Server Configuration

`GET /status` — Runtime Status

`GET /v1/pricing` — Rate Card

`GET /ready` — Readiness

JavaScript SDK

cURL Examples

Related Pages