Skip to content
Kheelona Voice

Limits, capacity and busy

Some limits are fixed. Some are set for your account by Kheelona: ask the Kheelona team if one gets in your way.

Sessions

Section titled “Sessions”
Limit Default Notes
Session length 1,800 s Set per partner by Kheelona, 60 to 3,600 s. A session can ask for less with max_duration_s, never more.
Idle timeout 120 s The longest a session stays open with nobody speaking and nothing playing. Set per partner, 30 to 600 s. Muting pauses the check-in and goodbye counts, not this timeout. A quiet session usually ends sooner: see Quiet sessions.
Client secret 60 s, single use See Sessions.
Reservation 60 s A session created but not connected.
Concurrent sessions set per partner Reserved and live sessions both count.
Monthly minutes set per partner, optional When it is used up, new sessions are refused with forbidden.
Languages 1 to 11 See Languages.
instructions 4,000 characters
metadata 10 keys, 200 characters per value, 2 KB in all Stored: no personal data.
end_user_ref 128 characters Letters, digits and . _ : - only.

Audio and events

Section titled “Audio and events”
Limit Value
Input audio speed at most 2 times real time, and at most 1 s ahead of real time
Input frame 10 to 500 ms
One WebSocket message 64 KB; a larger one closes the connection
One client event 8 KB
One typed turn (input.text) 2,000 characters
Typed turns per session 5 at once, then 1 per second. A turn beyond that is dropped and the session gets a non-fatal error with rate_limited (retryable: true). Send it again after a second.
One spoken turn 60 s of speech; a longer turn is cut and processed

API calls

Section titled “API calls”

Limits are per API key.

Calls Rate Burst
POST /v1/sessions 10 per second 20
Every other /v1 call 20 per second 40

Responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset, so you can slow down before you are refused. Over the limit you get 429 with rate_limited and a Retry-After. More than 20 failed authentications a minute from one IP address are refused for 10 minutes.

A relay normally creates one session per conversation, far below these rates. If a launch will create many sessions at once, tell us beforehand.

Capacity and “busy”

Section titled “Capacity and “busy””

Kheelona runs a fixed amount of speaking capacity: people talking and getting replies at the same moment. Kheelona sets it for the whole service, and sets how many sessions your account may run together.

A new session is checked when you create it, in this order: your account status, your monthly minutes, your concurrent sessions, then the capacity of the service. You get one of these answers:

  • 201: go ahead.
  • 429 partner_limit_reached: your account is at its concurrent-session limit. Wait for a session to end, then try again. If you need more, ask the Kheelona team.
  • 503 capacity_exhausted: the service is full right now. The answer has a Retry-After of 5 to 30 seconds. Wait that long and try again. For a toy, say something like “I’m busy, try again in a moment” from the device itself.
  • 503 capacity_exhausted with details.reason set: the voice service is not running right now. voice_service_starting means it is waking up: retry after 60 seconds (the answer’s Retry-After). voice_service_asleep means it is switched off to save cost: retry after 300 seconds, and tell the Kheelona team if it stays asleep when you need it.
  • 403 forbidden: the account is suspended or the monthly minutes are used up. Retrying will not help.

GET /v1/health needs no key and says capacity: available or busy. It is cached for 5 seconds, so use it to choose between two messages for the user, not to decide whether a session will succeed: only the create call decides.

See Errors and retries for how to retry.