API reference

Base URL https://realtimeavatar.ai/api/v1. Every request carries Authorization: Bearer tic_…. A machine-readable spec for the realtime surface lives at /openapi.json.

curl https://realtimeavatar.ai/api/v1/credits/balance \
  -H "Authorization: Bearer $REALTIME_AVATAR_API_KEY"

import { RealtimeAvatar } from "realtime-avatar";

const rta = new RealtimeAvatar({ apiKey: process.env.REALTIME_AVATAR_API_KEY! });
await rta.creditBalance();

import os, httpx

client = httpx.Client(
    base_url="https://realtimeavatar.ai/api/v1",
    headers={"Authorization": f"Bearer {os.environ['REALTIME_AVATAR_API_KEY']}"})

client.get("/credits/balance").json()

Realtime

Scenes (preview)

Enabled per workspace; other workspaces get 403 scene_sessions_not_enabled. A scene is a clip you supply, prepared once and then played as a call's picture: mint with scene: { video_cache_id } and the avatar keeps her voice and persona. You can read back and mint only scenes your workspace prepared; any other id is 404 scene_not_found. A mint also needs the scene to be ready, otherwise it answers 409 scene_not_ready (retryable while it is still building). Prepared scenes are kept for a limited time: a mint of one that has expired answers 404 scene_not_found, and preparing it again rebuilds it. A workspace holds at most 2 scene calls at once unless support raises it; another answers 429 scene_concurrency_limit_reached, retryable once one ends.

Connection history

Recordings

Avatars

Idle variations, events and actions

The source (primary) and authored idle clips form one weighted idle pool.idle.weights maps member IDs to finite weights from 0–100; each omitted member defaults to 1, zero disables it, and at least one must remain positive. Every member avoids immediately repeating when another is available; a sole available member loops completely. Do not combine this map with legacyidle.weight, which is converted into aggregate member weights. Lists are nonempty and cannot repeat a clip id. Unavailable members are filtered before selection and weights are renormalized. Ten idle variations are valid; there are no role-count or total-clip authoring caps beyond 32 per list. The 64 KB request-byte transport bound and worker admission remain independent constraints, not unlimited GPU capacity. If the source is disabled and every positive member is pending, mint returns retryable clip_library_not_ready.

userSpeechStarted plays one listening reaction, once per event, rather than holding a listening loop — a triggered reaction repeats freely. actions exposes the requestable menu: the language model reads each description to choose an appropriate action, then that action's clips list chooses a take; declaring an action never plays it by itself. The same clip can serve idle, listening and any action. Speaker lip-sync runs on the current playback cursor during full-duplex speech, without restarting the body on a separate talking clip.

Clip and action ids are 1–64 letters, digits, underscores, or hyphens; reserved keys are refused. Action descriptions are trimmed, nonempty, and at most 512 characters. Motion prompts are trimmed, nonempty, and at most 1,200 characters. Asset ids are trimmed, nonempty, and at most 160 characters. Strict objects reject unknown fields. Keep declaration writes server-owned; do not let caller-supplied prose bypass your application's policy or the platform's safety screening.

{
  "expectedRevision": 0,
  "clips": {
    "sway": { "source": { "motionPrompt": "Sways gently, settles back to rest" } },
    "nod": { "source": { "motionPrompt": "A gentle nod, then returns to rest", "durationSeconds": 5 } }
  },
  "idle": { "clips": ["sway", "nod"] },
  "on": {
    "userSpeechStarted": { "clips": ["nod"] }
  },
  "actions": {
    "agree": { "description": "When agreeing with the user", "clips": ["nod"] }
  }
}

Replace the sample revision with the latest GET revision. This full replacement retires records not shown here; include all existing records and behavior you intend to keep.

Assets

Billing and keys

Errors

Switch on code and HTTP status, not the wording of error. Correlated failures include a server-generated requestId, also in X-Request-ID; include it when contacting support. Session failures retain safe codes such as internal_error (500), capacity_unavailable and session_dispatch_failed (503), upstream_unreachable and invalid_upstream_response (502), upstream_timeout (504), and request_aborted (408). Internal diagnostics require separate operational access. A capacity queue 429 keeps its existing body; its request ID is in the header only.

Conventions

• All /api/v1 responses are Cache-Control: no-store.
• JSON request bodies are size-capped per route — 4 KiB on the session release and clip review, 64 KiB on session creation and the clip-library PUT, 128 KiB on avatar writes (create and update), and 8–32 KiB on other JSON routes. Field limits still apply within each byte budget. Over the body cap is a 413. Send media by URL, not inline.
• Idempotency-Key is honoured on the two writes that cost money to repeat — PUT /avatars/{id}/clips and PUT /avatars/{id}/loop. Replay returns the original response rather than doing the work twice. It matters most on the loop, where a repeated re-direct is a second billed render. A repeated clip declaration without the key has a stale expectedRevision after acceptance and conflicts; re-reading and declaring unchanged sources does not re-render them. Reuse the same key with a different body and you get a 409 — a retry means the same request, so generate a fresh key for a changed one. No other endpoint reads the header.
• 120 requests per 60 seconds, per key. The throttle is applied when the key is verified, so it covers every /api/v1 endpoint, and it counts per key rather than per workspace — splitting a workload across keys raises the ceiling. Over it is a 429 whose body carries no code and no queue fields, which is how you tell it from the other two. Worth sizing against: the creation flow asks you to poll GET /avatars/{id} until status is ready, and a render takes minutes — poll on the order of seconds, not milliseconds.
• Ids are prefixed and stable: ava_ avatars, tic_ API keys.
• The SDK covers the integration path — calls, avatars, assets, usage, credits — with a surface that is deliberately narrower than this wire, though less narrow than it once was. Avatar update and delete are in it (updateAvatar, deleteAvatar), as are getAvatar, listAvatars, listClips, setClipLibrary, retimeAnchor, swapSource and iterateSessions. Prefer it over hand-rolled fetches wherever it reaches. What it leaves out is key minting, the capacity snapshot and the asset listing — those three are a plain authenticated fetch against the endpoints above.