Guides

Models

The public model registry, per-request model switching, and what it costs in latency.

The API exposes stable public model ids that hide checkpoints and infrastructure. List them:

bash

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

json

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

Two model families, both conversational (every model serves converse and tts):

Model	Use it for
`kalpa-beta-v0.3`	The flagship — best quality; the default when `model` is omitted.
`kalpa-beta-v0.2`, `kalpa-beta-v0.1`	Earlier flagship-class variants, kept for comparison.
`kalpa-atom-beta-v0.1`	Atom — the compact family: fastest and cheapest to run.

Within a family, beta-vN increases with each new variant; newer is generally better.

Choosing a model per request

Every generation endpoint takes a model field:

json

{ "text": "…", "model": "kalpa-atom-beta-v0.1" }

Omit it (or send null) for the default model. The response's model field always echoes the resolved public id, so logs stay unambiguous.
An unknown id, or a model that doesn't support the endpoint's mode, returns 400 invalid_request.

Speakers are per model

Each card's speakers lists the role labels that model understands, in turn order. Don't hardcode them — read the card and use its labels. The details (and why wrong labels degrade audio) are in Conversations.

Switching cost

The default and Atom models are kept resident on the accelerator, so requests to them are always fast. Other models load on demand: the first request after a switch pays the load — up to tens of seconds for a flagship-class model (set client timeouts accordingly). If your traffic is latency-sensitive, prefer the resident models or keep it on one model rather than alternating.