Skip to main content

API Reference

Every Agent Avatar capability is a local HTTP endpoint. The engine is a FastAPI service that listens on port 8765 by default (override with PORT), so anything that can make an HTTP request can drive it — a script, a build step, or another tool in the Agent Software Suite.

Nothing here reaches the network beyond your own machine.

Authentication

Requests are authenticated. The engine can validate a service token or a short-lived ticket, configured through the AVATAR_AUTH_SERVER, AVATAR_SERVICE_TOKEN, and AVATAR_TICKET_SECRET environment variables. GET /auth/ticket issues a ticket for clients that need one.

If you set AVATAR_AUTH_SERVER, you must also set AVATAR_SERVICE_TOKEN — without it every request is rejected.

Long-running work is asynchronous

Generation endpoints return 202 Accepted with a job id rather than blocking. Poll the matching jobs endpoint for status and the output path.

Endpoints

Health and plugin

MethodPathPurpose
GET/healthLiveness check.
GET/plugin/manifestThe frozen v1.1 plugin manifest, for suite integration.
GET/auth/ticketIssue a short-lived auth ticket.

Speech

MethodPathPurpose
POST/tts/generateGenerate speech from text. Returns a job id.
GET/tts/jobs/{job_id}Job status, output path, and per-word timestamps.

Lip sync

MethodPathPurpose
POST/lipsync/generateRender one clip. Returns a job id.
GET/lipsync/jobs/{job_id}Status of a single render.
POST/lipsync/generate/batchRender every scene in a script, loading the model once.
GET/lipsync/jobs/batch/{job_id}Status of a batch render, per scene.

Face enhancement

MethodPathPurpose
POST/enhance/generateRun face restoration over a clip. Returns a job id.
GET/enhance/jobs/{job_id}Job status.

Catalog, voices, and avatars

MethodPathPurpose
GET/catalogRegistered voices, faces, and sources, with defaults.
GET/catalog/sources/{name}/videoStream a registered source clip.
GET/voicesTrained voice models available locally.
POST/avatars/warmPreload models so the first render is not the slow one.

Media and settings

MethodPathPurpose
GET/media/audioFetch generated audio.
GET/media/videoFetch generated video.
GET/settingsCurrent engine settings.
POST/settings/resetRestore default settings.
GET/bootstrap-configConfiguration a client needs on startup.

Backups

MethodPathPurpose
GET/backupsList backups.
GET/backups/dirsDirectories included in a backup.
POST/backupsCreate a backup.
POST/backups/{name}/restoreRestore from a backup.
DELETE/backups/{name}Delete a backup.

Batch is the interesting one

POST /lipsync/generate/batch is what makes Agent Avatar practical for real work. It loads MuseTalk once and renders every scene in your script against it, rather than paying model load cost per clip. If you are automating anything longer than a single line, use it.