Reference

API reference

Every endpoint, field and error — generated from the committed OpenAPI contract.

Kalpa Speech API v0.1.0, generated from the committed contract (openapi.json). Base URL https://api.kalpalabs.ai; bodies are JSON; authenticated endpoints take Authorization: Bearer $KALPA_API_KEY. HTTP errors before streaming begins use the envelope described in Rate limits & errors. Each endpoint except the WebSocket runs from this page: fill the fields, hit send — the request and response stay in sync on the right, copyable as curl, Python or JavaScript.

API key

Stored only in this browser and sent only to api.kalpalabs.ai. No key? Write to hello@kalpalabs.ai.

POST/v1/tts

Synthesize speech from text.

Render the given text as speech (24 kHz mono WAV) in the requested speaker's voice.

Body params

textrequired

string · 1 – 8000 chars

Text to speak.

model

string

Public model id (see GET /v1/models). Omit/null for the default model.

›params

object · 4 optional fields

acoustic_temperature

number · 0 – 1.5

Temperature for the voice's fine acoustic detail; null = follow temperature.

audio_quality

string · low | medium | high · default "high"

Playback fidelity: high = full quality (default); lower tiers reduce fidelity, not payload size.

max_new_tokens

integer · 16 – 2048

Optional generation cap; null uses the model's remaining context window.

temperature

number · 0 – 1.5 · default 0.9

speaker

string · default "0"

Speaker role to render the text as (one of the model's speakers; see GET /v1/models).

Response 200 · TtsResponse

audioAudioPayload

audio.audio_qualitystring

Fidelity tier this audio was rendered at (high = full quality).

audio.data_b64string

Base64-encoded 16-bit PCM WAV (mono).

audio.sample_rateinteger

Sample rate of the audio in Hz.

audio.formatstring

Container/encoding of data_b64 (16-bit PCM WAV).

modelstring

Resolved public model id that served the request.

request_idstring

Correlation id; identical to the X-Request-ID response header.

textstring

The text that was spoken (echoes the request).

usageUsage

usage.input_audio_secondsnumber

Seconds of input audio supplied (converse).

usage.input_charsinteger

Characters of input text billed for this request.

usage.output_audio_secondsnumber

Seconds of audio generated.

metaobject

Backend-specific diagnostics (latency, frames, …).

curl -s https://api.kalpalabs.ai/v1/tts \
  -H "Authorization: Bearer $KALPA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "text": "Hey there! How are you doing today?",
  "speaker": "0"
}'

200example

{
  "request_id": "9f2c1a46bdf94f55a49a48f1c3cb69e8",
  "model": "kalpa-tts-beta-v0.1",
  "text": "Hey there! How are you doing today?",
  "audio": {
    "format": "wav",
    "sample_rate": 24000,
    "audio_quality": "high",
    "data_b64": "UklGRiQAAABXQVZFZm10…"
  },
  "usage": {
    "input_chars": 35,
    "input_audio_seconds": 0,
    "output_audio_seconds": 2.6
  },
  "meta": {}
}

POST/v1/tts/{voice_id}

Synthesize speech from text in a named voice.

Render the given text as speech (24 kHz mono WAV) in one of the named voices from GET /v1/voices.

Path params

voice_idrequired

string

A named voice id, as listed by GET /v1/voices.

Body params

textrequired

string · 1 – 8000 chars

Text to speak.

model

string

Public model id (see GET /v1/models). Omit/null for the default model.

›params

object · 4 optional fields

acoustic_temperature

number · 0 – 1.5

Temperature for the voice's fine acoustic detail; null = follow temperature.

audio_quality

string · low | medium | high · default "high"

Playback fidelity: high = full quality (default); lower tiers reduce fidelity, not payload size.

max_new_tokens

integer · 16 – 2048

Optional generation cap; null uses the model's remaining context window.

temperature

number · 0 – 1.5 · default 0.9

Response 200 · TtsResponse

audioAudioPayload

audio.audio_qualitystring

Fidelity tier this audio was rendered at (high = full quality).

audio.data_b64string

Base64-encoded 16-bit PCM WAV (mono).

audio.sample_rateinteger

Sample rate of the audio in Hz.

audio.formatstring

Container/encoding of data_b64 (16-bit PCM WAV).

modelstring

Resolved public model id that served the request.

request_idstring

Correlation id; identical to the X-Request-ID response header.

textstring

The text that was spoken (echoes the request).

usageUsage

usage.input_audio_secondsnumber

Seconds of input audio supplied (converse).

usage.input_charsinteger

Characters of input text billed for this request.

usage.output_audio_secondsnumber

Seconds of audio generated.

metaobject

Backend-specific diagnostics (latency, frames, …).

curl -s https://api.kalpalabs.ai/v1/tts/8636013a-4e31-4cd4-b706-653d854a714b \
  -H "Authorization: Bearer $KALPA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "text": "Hey there! How are you doing today?"
}'

200example

{
  "request_id": "c77d02cb8b184744aa9cd8ad40a38866",
  "model": "kalpa-tts-beta-v0.1",
  "text": "Hey there! How are you doing today?",
  "audio": {
    "format": "wav",
    "sample_rate": 24000,
    "audio_quality": "high",
    "data_b64": "UklGRiQAAABXQVZFZm10…"
  },
  "usage": {
    "input_chars": 35,
    "input_audio_seconds": 0,
    "output_audio_seconds": 2.4
  },
  "meta": {}
}

WSS/v1/tts/{voice_id}/stream

Stream speech in a named voice over WebSocket. Stream text and flush to hear each utterance in the named voice, independently per flush.

Use one connection for one named voice (voice_id as listed by GET /v1/voices). Start with initializeConnection, then stream text with sendText and set flush to true to hear it. Each flushed utterance is generated independently in the connection's voice — no state carries from one response to the next. One response generates at a time; a flush sent mid-generation is queued (one slot) and starts when the current response settles, and a bare cancelResponse abandons everything undelivered — the in-flight generation, the queued utterance, and buffered text.

Client → server

›initializeConnection10 fields

Starts and authenticates the session. Send this message first.

typerequired"initializeConnection"

api_keyrequiredstring

Your Kalpa API key.

modelstring | null · default null

Model id. Omit for the default model.

generation_configGenerationConfig | null · default null

Enable and tune server-side segmentation of streamed text. Omit to generate only on flush.

generation_config.chunk_length_scheduleinteger[] · 1 – 10 items

Buffered-character thresholds before each successive segment of an utterance may start generating; the last value repeats. Lower values trade prosodic context for earlier first audio.

paramsGenParamsModel

Generation parameters for every response on this connection.

params.acoustic_temperaturenumber | null · 0 – 1.5 · default null

Temperature for the voice's fine acoustic detail; null = follow temperature.

params.audio_qualitystring · low | medium | high · default "high"

Playback fidelity: high = full quality (default); lower tiers reduce fidelity, not payload size.

params.max_new_tokensinteger | null · 16 – 2048 · default null

Optional generation cap; null uses the model's remaining context window.

params.temperaturenumber · 0 – 1.5 · default 0.9

›sendText3 fields

Adds text to the pending utterance. Set flush to true to generate its audio. A flush that arrives while a response is still generating is queued (one slot) and starts when that response settles; only a flush arriving while another is already queued is rejected.

typerequired"sendText"

textstring · default ""

Text to append to the utterance.

flushboolean · default false

Ends the utterance and starts generation when true.

›cancelResponse2 fields

Stops the current response. Without response_id it abandons everything undelivered — the in-flight generation, the queued utterance, and buffered text (nothing from an abandoned turn can leak into the next one; a discarded queued utterance produces no responseDone). With response_id it cancels that specific response only, leaving buffer and queue intact.

typerequired"cancelResponse"

response_idstring | null · default null

Response to cancel. Omit to cancel the current response.

Server → client

›sessionCreated8 fields

Confirms that the session is ready.

type"sessionCreated"

session_idstring

Id for this connection.

modelstring

Model serving the session.

voice_idstring

The named voice every response speaks in.

output_format"pcm_s16le"

Audio encoding for response chunks.

sample_rateinteger

Response audio sample rate in Hz.

channelsinteger

audio_qualitystring · low | medium | high

Fidelity tier responses are rendered at.

›responseCreated4 fields

Confirms that response generation has started.

type"responseCreated"

response_idstring

Id for this response.

sample_rateinteger

audio_qualitystring · low | medium | high

›responseAudio4 fields

A chunk of generated audio.

pcm_b64string

Base64-encoded raw PCM audio.

response_idstring

frameinteger | null

Backend frame counter; informational.

type"responseAudio"

›responseDone9 fields

Confirms that the response has completed or was cancelled.

type"responseDone"

response_idstring

statusstring · completed | cancelled

textstring

Text for the response.

usageUsage

usage.input_charsinteger

Characters of input text billed for this request.

usage.input_audio_secondsnumber

Seconds of input audio supplied (converse).

usage.output_audio_secondsnumber

Seconds of audio generated.

metaobject

Public generation timing and runtime metadata.

›error7 fields

Reports a WebSocket error.

type"error"

fatalboolean

True when the connection is about to close.

errorWsErrorBody

error.typestring

error.messagestring

error.request_idstring | null

Id for the session or response.

response_idstring | null

Present when the error belongs to a specific generation.

Close codes

Code	Meaning	Client action
`1011`	Internal server error.	Retry.
`4400`	Protocol violation.	Fix the message before reconnecting.
`4401`	Authentication failed.	Check the API key.
`4404`	Unknown voice id.	See `GET /v1/voices` for the available voices.
`4408`	Initialization or idle timeout.	Reconnect.
`4429`	Reserved for rate limiting; not currently emitted.	Retry with backoff.
`4503`	API-key verification is temporarily unavailable.	Retry with the same key.

# pip install websockets
import asyncio, base64, json, os
import websockets

VOICE_ID = "…"  # a voice id from GET /v1/voices

async def main():
    url = f"wss://api.kalpalabs.ai/v1/tts/{VOICE_ID}/stream"
    async with websockets.connect(url) as ws:
        await ws.send(json.dumps({
            "type": "initializeConnection",
            "api_key": os.environ["KALPA_API_KEY"],
        }))
        await ws.recv()  # sessionCreated
        await ws.send(json.dumps({
            "type": "sendText",
            "text": "Hello from Kalpa.", "flush": True,
        }))

        audio = bytearray()
        async for raw in ws:
            message = json.loads(raw)
            if message["type"] == "responseAudio":
                audio += base64.b64decode(message["pcm_b64"])
            elif message["type"] == "responseDone":
                break

        open("out.pcm", "wb").write(audio)

asyncio.run(main())

Both clients save the streamed mono, 16-bit PCM audio to out.pcm. Use the sample rate returned by sessionCreated for playback.

POST/v1/converse

Complete the open (final) turn of a conversation.

Given a conversation, complete its last ('open') turn. A speaker-only open turn is authored (text + audio); an open turn with text is rendered as that speaker, conditioned on the prior turns (contextual TTS).

Body params

conversationrequired

array · 1 – 64 items

The conversation, oldest turn first; the last turn is the open turn to complete.

turn 1

audio_wav_b64

upload

speaker

text

turn 2 · open turn (completed by the model)

audio_wav_b64

upload

speaker

text

model

string

Public model id (see GET /v1/models). Omit/null for the default model.

›params

object · 4 optional fields

acoustic_temperature

number · 0 – 1.5

Temperature for the voice's fine acoustic detail; null = follow temperature.

audio_quality

string · low | medium | high · default "high"

Playback fidelity: high = full quality (default); lower tiers reduce fidelity, not payload size.

max_new_tokens

integer · 16 – 2048

Optional generation cap; null uses the model's remaining context window.

temperature

number · 0 – 1.5 · default 0.9

Response 200 · ConverseResponse

modelstring

Resolved public model id that served the request.

replyConverseReply

reply.speakerstring

reply.textstring

reply.audioAudioPayload | null

reply.audio.audio_qualitystring

Fidelity tier this audio was rendered at (high = full quality).

reply.audio.data_b64string

Base64-encoded 16-bit PCM WAV (mono).

reply.audio.sample_rateinteger

Sample rate of the audio in Hz.

reply.audio.formatstring

Container/encoding of data_b64 (16-bit PCM WAV).

request_idstring

Correlation id; identical to the X-Request-ID response header.

usageUsage

usage.input_audio_secondsnumber

Seconds of input audio supplied (converse).

usage.input_charsinteger

Characters of input text billed for this request.

usage.output_audio_secondsnumber

Seconds of audio generated.

metaobject

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"
    }
  ]
}'

200example

{
  "request_id": "4b81de599ee148bc9df8327ec9ed1810",
  "model": "kalpa-tts-beta-v0.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": "UklGRiQAAABXQVZFZm10…"
    }
  },
  "usage": {
    "input_chars": 16,
    "input_audio_seconds": 0,
    "output_audio_seconds": 3.2
  },
  "meta": {}
}

POST/v1/converse/stream

Complete the open turn, streaming audio as it is generated.

Same request as /v1/converse; the response is a text/event-stream: one meta event, audio chunk events as audio is generated (pcm_b64 = base64 raw 16-bit LE PCM at sample_rate), then exactly one end (reply text, audio_seconds, usage, meta) or error. First audio arrives after one ~80 ms frame instead of after the whole clip; closing the connection aborts generation.

Body params

conversationrequired

array · 1 – 64 items

The conversation, oldest turn first; the last turn is the open turn to complete.

turn 1

audio_wav_b64

upload

speaker

text

turn 2 · open turn (completed by the model)

audio_wav_b64

upload

speaker

text

model

string

Public model id (see GET /v1/models). Omit/null for the default model.

›params

object · 4 optional fields

acoustic_temperature

number · 0 – 1.5

Temperature for the voice's fine acoustic detail; null = follow temperature.

audio_quality

string · low | medium | high · default "high"

Playback fidelity: high = full quality (default); lower tiers reduce fidelity, not payload size.

max_new_tokens

integer · 16 – 2048

Optional generation cap; null uses the model's remaining context window.

temperature

number · 0 – 1.5 · default 0.9

Response 200

text/event-stream: one meta event, repeated audio events, then exactly one end or error.

curl -sN https://api.kalpalabs.ai/v1/converse/stream \
  -H "Authorization: Bearer $KALPA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "conversation": [
    {
      "speaker": "0",
      "text": "Hi, who are you?"
    },
    {
      "speaker": "1"
    }
  ]
}'

200example

event: meta
data: {"model":"kalpa-tts-beta-v0.1","mode":"converse_author","sample_rate":24000,"audio_quality":"high","context_turns":1}

event: audio
data: {"pcm_b64":"…","frame":1}

event: end
data: {"request_id":"4b81de599ee148bc9df8327ec9ed1810","text":"I'm a speech model built by Kalpa Labs.","sample_rate":24000,"audio_quality":"high","audio_seconds":3.2,"usage":{"input_chars":16,"input_audio_seconds":0.0,"output_audio_seconds":3.2},"meta":{"mode":"converse_author","context_turns":1}}

WSS/v1/converse/stream

Stream a stateful conversation over WebSocket. Send JSON messages to build the conversation and receive audio as it is generated.

Use one connection for one conversation. Start with initializeConnection, then send text or add completed turns. The server keeps the conversation history until the socket closes and returns generated audio as responseAudio messages.

Client → server

›initializeConnection9 fields

Starts and authenticates the WebSocket session. Send this message first.

typerequired"initializeConnection"

api_keyrequiredstring

Your Kalpa API key.

modelstring | null · default null

Model id. Omit for the default model.

history_limitinteger | null · 1 – 64 · default null

Optional rolling number of completed turns retained for each response.

paramsGenParamsModel

Generation parameters for every response on this connection.

params.acoustic_temperaturenumber | null · 0 – 1.5 · default null

Temperature for the voice's fine acoustic detail; null = follow temperature.

params.audio_qualitystring · low | medium | high · default "high"

Playback fidelity: high = full quality (default); lower tiers reduce fidelity, not payload size.

params.max_new_tokensinteger | null · 16 – 2048 · default null

Optional generation cap; null uses the model's remaining context window.

params.temperaturenumber · 0 – 1.5 · default 0.9

›sendText4 fields

Adds text to the current turn. Set flush to true to generate the response.

typerequired"sendText"

speaker_idinteger | null · ≥ 0 · default null

Speaker for this turn. Required on the first sendText message.

textstring · default ""

Text to append to the turn.

flushboolean · default false

Ends the turn and starts generation when true.

›addTurn4 fields

Adds a completed text-and-audio turn to the conversation history.

typerequired"addTurn"

speaker_idrequiredinteger · ≥ 0

textrequiredstring · ≥ 1 chars

Transcript for the audio.

audio_wav_b64requiredstring · ≥ 1 chars

Base64-encoded WAV audio.

›cancelResponse2 fields

Stops the current response.

typerequired"cancelResponse"

response_idstring | null · default null

Response to cancel. Omit to cancel the current response.

Server → client

›sessionCreated7 fields

Confirms that the session is ready.

type"sessionCreated"

session_idstring

Id for this conversation.

modelstring

Model serving the session.

output_format"pcm_s16le"

Audio encoding for response chunks.

sample_rateinteger

Response audio sample rate in Hz.

channelsinteger

audio_qualitystring · low | medium | high

Fidelity tier responses are rendered at.

›responseCreated5 fields

Confirms that response generation has started.

type"responseCreated"

response_idstring

Id for this response.

speaker_idinteger

Speaker for this response.

sample_rateinteger

audio_qualitystring · low | medium | high

›responseAudio4 fields

A chunk of generated audio.

pcm_b64string

Base64-encoded raw PCM audio.

response_idstring

frameinteger | null

Backend frame counter; informational.

type"responseAudio"

›responseDone10 fields

Confirms that the response has completed or was cancelled.

type"responseDone"

response_idstring

speaker_idinteger

statusstring · completed | cancelled

textstring

Text for the response.

usageUsage

usage.input_charsinteger

Characters of input text billed for this request.

usage.input_audio_secondsnumber

Seconds of input audio supplied (converse).

usage.output_audio_secondsnumber

Seconds of audio generated.

metaobject

Public generation timing and runtime metadata.

›error7 fields

Reports a WebSocket error.

type"error"

fatalboolean

True when the connection is about to close.

errorWsErrorBody

error.typestring

error.messagestring

error.request_idstring | null

Id for the session or response.

response_idstring | null

Present when the error belongs to a specific generation.

Close codes

Code	Meaning	Client action
`1011`	Internal server error.	Retry.
`4400`	Protocol violation.	Fix the message before reconnecting.
`4401`	Authentication failed.	Check the API key.
`4408`	Initialization or idle timeout.	Reconnect.
`4429`	Reserved for rate limiting; not currently emitted.	Retry with backoff.
`4503`	API-key verification is temporarily unavailable.	Retry with the same key.

# pip install websockets
import asyncio, base64, json, os
import websockets

async def main():
    async with websockets.connect("wss://api.kalpalabs.ai/v1/converse/stream") as ws:
        await ws.send(json.dumps({
            "type": "initializeConnection",
            "api_key": os.environ["KALPA_API_KEY"],
        }))
        await ws.recv()  # sessionCreated
        await ws.send(json.dumps({
            "type": "sendText", "speaker_id": 0,
            "text": "Hello from Kalpa.", "flush": True,
        }))

        audio = bytearray()
        async for raw in ws:
            message = json.loads(raw)
            if message["type"] == "responseAudio":
                audio += base64.b64decode(message["pcm_b64"])
            elif message["type"] == "responseDone":
                break

        open("out.pcm", "wb").write(audio)

asyncio.run(main())

Both clients save the streamed mono, 16-bit PCM audio to out.pcm. Use the sample rate returned by sessionCreated for playback.

GET/v1/models

List available public models.

Response 200 · ModelsResponse

dataModelCard[]

The available public models.

data[].display_namestring

Human-readable model name.

data[].idstring

Stable public model id used in the model request field.

data[].modesstring[]

Supported modes: subset of ["converse", "tts"].

data[].speakersstring[]

Valid role labels for a turn's speaker, in turn order (e.g. ["0", "1"]).

data[].defaultboolean

True for the model used when model is omitted.

data[].descriptionstring

What this model is for.

data[].languagesstring[]

Languages the model speaks, as ISO 639-1 codes (e.g. ["en", "hi"]).

curl -s https://api.kalpalabs.ai/v1/models \
  -H "Authorization: Bearer $KALPA_API_KEY"

200example

{
  "data": [
    {
      "id": "kalpa-tts-beta-v0.1",
      "display_name": "Kalpa TTS beta v0.1",
      "description": "English conversational speech model (dialogue + TTS) — best quality; the default.",
      "modes": [
        "converse",
        "tts"
      ],
      "speakers": [
        "0",
        "1"
      ],
      "languages": [
        "en"
      ],
      "default": true
    },
    {
      "id": "kalpa-tts-multilingual-beta-v0.1",
      "display_name": "Kalpa TTS multilingual beta v0.1",
      "description": "Multilingual conversational speech model (dialogue + TTS) — English and Hindi.",
      "modes": [
        "converse",
        "tts"
      ],
      "speakers": [
        "0",
        "1"
      ],
      "languages": [
        "en",
        "hi"
      ],
      "default": false
    }
  ]
}

GET/v1/voices

List available named voices.

Response 200 · VoicesResponse

dataVoiceCard[]

The available named voices.

data[].genderstring

Perceived voice gender.

data[].idstring

Stable public voice id, used as the /v1/tts/{voice_id} path segment.

data[].namestring

Human-readable voice name.

curl -s https://api.kalpalabs.ai/v1/voices \
  -H "Authorization: Bearer $KALPA_API_KEY"

200example

{
  "data": [
    {
      "id": "8636013a-4e31-4cd4-b706-653d854a714b",
      "name": "June",
      "gender": "feminine"
    },
    {
      "id": "c08d0442-e96a-471d-808e-43563061a508",
      "name": "Cole",
      "gender": "masculine"
    }
  ]
}

GET/v1/info

Backend info, default params, and limits.

Response 200 · InfoResponse

backendInfoBackend

Active gateway/backend description.

backend.detailstring

backend.kindstring

backend.namestring

backend.readyboolean

backend.sample_rateinteger

defaultsGenParamsModel

Default generation parameters.

defaults.acoustic_temperaturenumber | null

Temperature for the voice's fine acoustic detail; null = follow temperature.

defaults.audio_qualitystring

Playback fidelity: high = full quality (default); lower tiers reduce fidelity, not payload size.

defaults.max_new_tokensinteger | null

Optional generation cap; null uses the model's remaining context window.

defaults.temperaturenumber

limitsInfoLimits

Effective request caps and rate limits for this key.

limits.max_audio_bytesinteger

limits.max_conversation_turnsinteger

limits.max_text_charsinteger

limits.rate_limit_burstinteger

limits.rate_limit_rpminteger

param_schemaParamSchemaEntry[]

UI metadata for the generation parameters.

param_schema[].helpstring

param_schema[].keystring

param_schema[].labelstring

param_schema[].typestring

param_schema[].deprecatedboolean

param_schema[].maxnumber

param_schema[].minnumber

param_schema[].nullableboolean

param_schema[].offLabelstring

param_schema[].optionsinteger | string[]

param_schema[].stepnumber

curl -s https://api.kalpalabs.ai/v1/info \
  -H "Authorization: Bearer $KALPA_API_KEY"

200example

{
  "backend": {
    "name": "Kalpa gateway (http)",
    "kind": "http",
    "ready": true,
    "sample_rate": 24000,
    "detail": "default=kalpa-tts-beta-v0.1 · variants=2"
  },
  "defaults": {
    "temperature": 0.9,
    "acoustic_temperature": null,
    "max_new_tokens": null,
    "audio_quality": "high"
  },
  "limits": {
    "max_text_chars": 8000,
    "max_conversation_turns": 64,
    "max_audio_bytes": 26214400,
    "rate_limit_rpm": 600,
    "rate_limit_burst": 120
  },
  "param_schema": [
    {
      "key": "temperature",
      "label": "Temperature",
      "type": "slider",
      "min": 0,
      "max": 1.5,
      "step": 0.05,
      "help": "Sampling temperature for the words and delivery. 0 = deterministic."
    },
    {
      "key": "acoustic_temperature",
      "label": "Acoustic temperature",
      "type": "slider",
      "min": 0,
      "max": 1.5,
      "step": 0.05,
      "nullable": true,
      "offLabel": "linked",
      "help": "Temperature for the voice's fine acoustic detail. Linked to Temperature when unset."
    },
    {
      "key": "max_new_tokens",
      "label": "Max new tokens",
      "type": "int",
      "min": 16,
      "max": 2048,
      "step": 16,
      "nullable": true,
      "offLabel": "context limit",
      "help": "Optional generation cap. Unset = generate until a stop token or the model's context limit."
    },
    {
      "key": "audio_quality",
      "label": "Audio quality",
      "type": "select",
      "options": [
        "low",
        "medium",
        "high"
      ],
      "help": "Playback fidelity. High is full quality; lower tiers reduce fidelity, not payload size."
    }
  ]
}

GET/v1/usage

Your metered usage.

Durable usage totals (requests, input characters, audio seconds) for the calling API key. Without parameters, lifetime totals. With start_time/end_time (ISO 8601), totals for that window at hourly granularity: the effective window snaps outward to hour boundaries and is echoed back in the response.

Response 200 · UsageSummaryResponse

input_audio_secondsnumber

input_charsinteger

key_idstring

Non-secret identifier of the API key whose usage is summarized.

output_audio_secondsnumber

requestsinteger

end_timestring | null

Effective (hour-snapped) window end, exclusive; windowed queries only.

first_request_tsnumber | null

Unix time of the first metered request (lifetime queries).

last_request_tsnumber | null

Unix time of the latest metered request (lifetime queries).

start_timestring | null

Effective (hour-snapped) window start; windowed queries only.

curl -s https://api.kalpalabs.ai/v1/usage \
  -H "Authorization: Bearer $KALPA_API_KEY"

200example

{
  "key_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
  "requests": 1284,
  "input_chars": 91230,
  "input_audio_seconds": 411,
  "output_audio_seconds": 3120.5,
  "last_request_ts": 1751500000
}

GET/health

Liveness probe. No authentication.

Response 200 · HealthResponse

backendstring

readyboolean

statusstring