# TIC Realtime Avatar API

> Realtime AI avatar platform. Create avatars from a portrait image or source video, then either stream realtime audio-clocked avatar turns over HTTP, or render a pre-recorded audio URL to a talking-head MP4 (non-streaming lipsync). Typed TypeScript and Python SDKs, credit-based usage billing, scoped API keys with test/live environments, remote MCP server for AI agents.

Base URL: https://realtimeavatar.ai

## Machine-readable surface

- OpenAPI 3.1 spec: https://realtimeavatar.ai/openapi.json
- Remote MCP server (Streamable HTTP): https://realtimeavatar.ai/api/mcp
  - Claude Code: `claude mcp add --transport http tic-avatar https://realtimeavatar.ai/api/mcp --header "Authorization: Bearer tic_test_..."`
  - Tools: get_pricing (no auth), check_credits, list_avatars, get_avatar, create_avatar_from_url, prepare_avatar, lipsync, create_api_key. `lipsync` is fully self-contained (audio URL in, MP4 URL out); the streaming turn data plane stays on HTTP (`POST /api/v1/realtime/turn`).

## Authentication

- All `/api/v1/*` endpoints require `Authorization: Bearer <api_key>`.
- Key formats: `tic_live_<keyId>_<secret>` (production) and `tic_test_<keyId>_<secret>` (test environment).
- Keys carry scopes: `avatars:read`, `avatars:write`, `realtime:write`, `credits:read`, `api_keys:write`, `usage:read`, `usage:write`, or `*`.
- Get a key: sign up at `/platform` (free sandbox plan), then create keys in `/platform/dashboard`. Existing keys with the `api_keys:write` scope can mint additional keys programmatically via `POST /api/v1/api-keys` or the MCP `create_api_key` tool.

## API endpoints

- `GET /api/v1/avatars` — list your avatars (scope: `avatars:read`).
- `POST /api/v1/avatars` — create an avatar from an uploaded asset (scope: `avatars:write`).
- `GET /api/v1/avatars/{avatarId}` — avatar details and readiness; ids start with `ava_` (scope: `avatars:read`).
- `PATCH /api/v1/avatars/{avatarId}` — update name, voice, settings (scope: `avatars:write`).
- `DELETE /api/v1/avatars/{avatarId}` — delete an avatar (scope: `avatars:write`).
- `GET /api/v1/assets` — list uploaded assets (scope: `avatars:read`).
- `POST /api/v1/assets` — multipart upload (`file` field) of an image/video/audio asset (scope: `avatars:write`).
- `POST /api/v1/assets/remote` — ingest an asset from a public URL (scope: `avatars:write`).
- `POST /api/v1/realtime/prepare` — warm/register an avatar for realtime; call once before a session (scope: `realtime:write`).
- `POST /api/v1/realtime/turn` — run a realtime turn; streams an audio-clocked binary mux of audio + video frames; decode with `readAvatarMux` from the SDK (scope: `realtime:write`).
- `POST /api/v1/lipsync` — non-streaming lipsync: pass `audioUrl` + (`avatarId` or `portraitUrl`); downloads the audio, renders the full clip, and returns a stored MP4 URL as JSON. No streaming/playback needed — ideal for backend and batch jobs (scope: `realtime:write`).
- `POST /api/v1/realtime/video-cache/plan` — plan source-video cache generation (scope: `avatars:write`).
- `GET /api/v1/credits/balance` — credit wallet: available, reserved, lifetime usage (scope: `credits:read`).
- `POST /api/v1/api-keys` — create a new scoped API key (scope: `api_keys:write`).

## Credits, billing, and errors

- Usage is billed in credit micros; 1 second of realtime rendering = 1,000,000 credit micros.
- Realtime turns reserve estimated credits up front and settle to actual usage afterward; settlement never exceeds the reservation. Send an `Idempotency-Key` header on turns — reusing a key returns `409`.
- Error semantics (body is `{"error": "<message>"}`): `401` invalid or missing API key; `403` insufficient scope or suspended tenant; `402` insufficient credits or key spend limit exceeded — top up or upgrade at `/platform/billing`; `429` rate limited.

## Plans

- Realtime time is anchored at ~$5/hour across plans.
- sandbox — free: 5 realtime minutes/month, 1 avatar (hard cap), no overage.
- developer — $49/month: 600 realtime minutes (10 hours), $0.085/min overage, 25 avatars included then $1 per avatar creation, 2 concurrent sessions.
- studio — $249/month: 3,000 realtime minutes (50 hours), $0.08/min overage, 100 avatars included then $1 each, 10 concurrent sessions.
- scale — $999/month: 13,000 realtime minutes (216 hours), $0.07/min overage, 500 avatars included then $1 each, 50 concurrent sessions.
- Avatar sources: a single image, or a video clip of 10 seconds or less (max 32MB). Uploads are vision-checked (single subject, mostly frontal, face visible); rejected sources return HTTP 422 with corrective advice.

## SDK

- `realtime-avatar` (npm) — typed TypeScript SDK generated from OpenAPI. Entry points: `RealtimeAvatarClient` (core, incl. `client.lipsync(...)` and `client.turn(...)`), `realtime-avatar/browser` (`AvatarPlayer` canvas renderer), `realtime-avatar/react` (`useAvatarSession`, `AvatarStage`), `realtime-avatar/server` (backend-only key hashing).
- `realtime-avatar` (PyPI) — lean Python client (`httpx`): `RealtimeAvatarClient`/`AsyncRealtimeAvatarClient` with `lipsync`, `prepare`, `list_avatars`, `credit_balance`.
- Streaming flow: create avatar → `POST /api/v1/realtime/prepare` → `POST /api/v1/realtime/turn` (binary mux stream) → render with `AvatarPlayer`.
- Batch flow: create avatar → `client.lipsync({ audioUrl, avatarId })` → use the returned MP4 URL.
- Docs: https://docs.realtimeavatar.ai

## Resources

- Developer landing and pricing: https://realtimeavatar.ai/platform
- Dashboard (API keys, usage, billing): https://realtimeavatar.ai/platform/dashboard
- Journal (blog: realtime characters, agentic content pipelines; some posts localized zh/ja): https://realtimeavatar.ai/blog