API Reference

HTTP endpoints, WebSocket connections, authentication, and the audio pipeline.

Base URL

Default: http://127.0.0.1:9999. The server binds to 0.0.0.0:9999 by default.

Authentication

Set FACE_API_KEY env var to require auth on the self-hosted server. Clients authenticate via:

Authorization: Bearer <key>
// or query param
/api/state?token=<key>

GitHub OAuth (oface.io)

oface.io uses GitHub OAuth for identity. When GITHUB_CLIENT_ID is configured, claiming a face requires logging in with GitHub. Sessions are stored in KV with a 7-day TTL. OAuth is optional — when not configured, claim works without login.

HTTP Endpoints

curl -X POST http://127.0.0.1:9999/api/state \
  -H "Content-Type: application/json" \
  -d '{"state":"speaking","emotion":"happy","text":"Hello!"}'

curl -X POST http://127.0.0.1:9999/api/speak
// Response: { "seq": 1 }

curl -X POST http://127.0.0.1:9999/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"What needs to change?"}'

WebSocket

Messages are JSON state objects. Viewers also receive type: "audio" (base64 WAV), type: "audio-seq" (new sequence), type: "audio-done", and type: "history" (replay on connect).

Audio Pipeline

Single authority model — no race conditions:

The viewer computes mouth amplitude from actual waveform data, so lip sync follows real audio rather than guessed network values.

Built-in TTS Fallback

The <open-face> element supports browser-native text-to-speech as a zero-config fallback. Add the tts attribute and any text in state messages will be spoken aloud:

<open-face server="ws://localhost:9999/ws/viewer" tts></open-face>

When TTS is enabled:

• External audio pipeline always takes priority — TTS stays silent while WAV chunks are flowing
• Face auto-transitions to speaking on utterance start, idle on end
• Amplitude is simulated from word boundary events
• Optional: tts-voice, tts-rate (0.1-10), tts-pitch (0-2) attributes

oface.io Product API

All local server endpoints also work per-face on oface.io. Each claimed username gets its own isolated Durable Object with persistent state and WebSocket connections.

Claim a Face

curl -X POST https://oface.io/api/claim \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","face":"zen"}'

# Response:
{
  "ok": true,
  "apiKey": "oface_ak_xxxxxxxxxxxx",
  "url": "https://oface.io/alice",
  "wsViewer": "wss://oface.io/alice/ws/viewer",
  "wsAgent": "wss://oface.io/alice/ws/agent"
}

Check Availability

curl https://oface.io/api/check/alice
# { "available": true }

curl https://oface.io/api/check/admin
# { "available": false, "reason": "reserved" }

Per-Face State

curl -X POST https://oface.io/alice/api/state \
  -H "Authorization: Bearer oface_ak_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"state":"speaking","emotion":"happy","text":"Hello!"}'

Face Config

curl -X PUT https://oface.io/alice/api/config \
  -H "Authorization: Bearer oface_ak_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"face":"cyberpunk","head":{"enabled":true}}'

Per-Face WebSocket

Per-Face Audio

The same audio pipeline works per-face on oface.io:

Per-Face Viewer and Dashboard

Community Gallery API

The community gallery lets users submit and browse face packs. Submissions are rate-limited to 10 per IP per hour. Authenticated users (via GitHub OAuth) get their verified GitHub username as the pack author.

Admin API

Admin endpoints require a valid GitHub OAuth session with a username in the admin set. Used for gallery moderation and claim management.

Account API

Authenticated users can manage their own claimed faces and gallery submissions. All endpoints require a valid GitHub OAuth session (cookie-based).

Ownership is enforced — you can only see and modify resources tied to your GitHub username. Manage your account at openface.live/account.

Rate Limiting

Token bucket per IP. Default: 60 messages/second per agent. Gallery submissions: 10 per IP per hour. Configurable via environment.

MCP Tools

8 tools for Claude-compatible clients:

FACE_URL=http://127.0.0.1:9999 bun packages/mcp/src/index.ts

Programmatic Pack Generation

The @openface/renderer package includes a face generator that produces complete face packs from high-level inputs. Generated packs can be pushed to the config API or used directly with the renderer.

See the Face Pack Guide for usage examples.

Environment Variables