Rate limits

Request limits

Requests are limited per account (every API secret on the account shares the same buckets), by endpoint cost tier and plan. Each cell is requests per minute; a bucket also allows a burst of that size and refills continuously.

* Enterprise defaults; custom limits are available from sales.

A plan change reaches the limiter within about a minute; no new secret is needed. Over the limit, the API returns 429 RATE_LIMITED with a Retry-After header and the standard error envelope.

Never limited: webhook deliveries, and the runtime-token routes (/v1/runtime-tokens*, /v1/runtime/*) that keep a live session authenticated. A live session is never cut off with a 429.

Failed authentication is throttled per client IP at 30 failures per minute. Routes that check the secret themselves (embed-token and realtime mints, /v1/me, CLI sign-in) are limited per client IP, at 120 requests per minute, instead of per account.

Session concurrency

A session over the allowance is refused at start with 403 CONCURRENCY_LIMIT_REACHED, whose upgrade_url links the plans; a live session is never cut off by this limit. Every cloud avatar counts as its own session, including avatars that share a room name. Agent and dynamics generation jobs queue and run as capacity frees up.

A session stops counting the moment it ends: the room closes, the last user leaves, or you remove the avatar participant (bithuman-avatar-agent) from your LiveKit room. That holds for every cloud session: the Console, the web embed, and a cloud avatar in your own LiveKit room. To end one yourself and free its slot at once, terminate the session.

Session length. One continuous session can run up to 24 hours in the cloud and 7 days self-hosted. It then ends with 403 SESSION_DURATION_LIMIT; start a new session to continue. For longer unattended installs (kiosks), contact sales.

Sessions you render on your own hardware are limited only by your credits (self-hosting). Cost: active session time, to the second (pricing).

Response headers

Metered endpoints return your current state, so you can slow down before a 429:

Not every response carries them (POST /v1/validate has none); fall back to backoff.

Recommended retry strategy

Retry 429 and 5xx with exponential backoff and jitter, honouring Retry-After:

import time, random, requests

def call(method, url, max_retries=5, **kw):
    for attempt in range(max_retries):
        resp = requests.request(method, url, timeout=30, **kw)
        if resp.status_code not in (429, 502, 503, 504):
            return resp
        wait = float(resp.headers.get("Retry-After", 2 ** attempt))
        time.sleep(wait + random.uniform(0, 1))
    return resp

Usage: call("POST", "https://api.bithuman.ai/v1/video/generate", headers=h, json={...}).

Best practices

• Use webhooks, not polling, for agent.ready and agent.failed. If you poll status, poll every 5 seconds or slower.
• Cache agent details from GET /v1/agent/{code}; they rarely change.
• Reuse a session for back-to-back conversations rather than starting a new one; note that an open session bills its time, talking or idle.
• Check your balance with GET /v2/credit-summaries before creating an agent (creation costs), to avoid a 402.

More capacity comes with a higher plan; for more than Enterprise, contact sales.