Kalpa LabsDocs
DashboardGet API key
Start

Quickstart

From API key to spoken audio in five minutes: one TTS call, then a conversation.

1. Get a key

Create one yourself at kalpalabs.ai/dashboard/keys; new accounts get 1,000 free minutes of generated audio (on your first organization, valid for three months). Keep it server-side and export it where your code runs:

Shell
export KALPA_API_KEY=...

2. Say something

POST /v1/tts/{voice_id} takes text and returns it spoken in a named voice, as base64 WAV. This call uses Wren, one of the voices in GET /v1/voices. Decode the response and you have a playable file:

Shell
curl -s https://api.kalpalabs.ai/v1/tts/dda5319f-3b81-4124-b69e-9241eb510b77 \
  -H "Authorization: Bearer $KALPA_API_KEY" -H 'Content-Type: application/json' \
  -d '{"text": "Hey there! How are you doing today?"}' \
  | python3 -c 'import sys,json,base64; r=json.load(sys.stdin); open("out.wav","wb").write(base64.b64decode(r["audio"]["data_b64"])); print("wrote out.wav", r["usage"])'
200audio.data_b64Wren · kalpa-tts-1
0:02

out.wav is mono 16-bit PCM at 24 kHz. The same call in Python:

Python
import base64, requests, os

r = requests.post(
    "https://api.kalpalabs.ai/v1/tts/dda5319f-3b81-4124-b69e-9241eb510b77",
    headers={"Authorization": f"Bearer {os.environ['KALPA_API_KEY']}"},
    json={"text": "Hey there! How are you doing today?"},
)
r.raise_for_status()
reply = r.json()
with open("out.wav", "wb") as f:
    f.write(base64.b64decode(reply["audio"]["data_b64"]))
print(reply["usage"])  # characters in, seconds of audio out
200audio.data_b64Wren · kalpa-tts-1
0:02

3. Have a conversation

POST /v1/converse completes the last turn of a conversation. Here the last turn carries only a speaker — so the model authors it: it writes what speaker "1" would say next and voices it.

Shell
curl -s https://api.kalpalabs.ai/v1/converse \
  -H "Authorization: Bearer $KALPA_API_KEY" -H 'Content-Type: application/json' \
  -d '{
    "conversation": [
      {"speaker": "0", "text": "Hi, who are you?"},
      {"speaker": "1"}
    ]
  }'
JSON
{
  "request_id": "…",
  "model": "kalpa-tts-1",
  "reply": {
    "speaker": "1",
    "text": "I'm a speech model built by Kalpa Labs…",
    "audio": { "format": "wav", "sample_rate": 24000, "audio_quality": "high", "data_b64": "…" }
  },
  "usage": { "input_chars": 16, "input_audio_seconds": 0.0, "output_audio_seconds": 3.2 },
  "meta": { "mode": "converse_author", "context_turns": 1 }
}

request_id is the request's correlation id, not a generation parameter. It matches the X-Request-ID response header and can be supplied by your client; see Request IDs.

Give the last turn a text instead and the model renders exactly that text in context — contextual TTS. The full semantics (spoken history, reference audio, speaker labels) are in Conversations.

Next