Quickstart

// npm install ws
import WebSocket from "ws";
import { readFileSync } from "node:fs";

const API = process.env.FACEMODE_API_URL ?? "https://api.facemode.io/api";
const KEY = process.env.FACEMODE_API_KEY;
const headers = { "x-api-key": KEY, "Content-Type": "application/json" };

// 1. Create the session
const createRes = await fetch(`${API}/sessions`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    avatarId: process.env.FACEMODE_AVATAR_ID,
    room: { type: "livekit", url: process.env.LIVEKIT_URL, token: process.env.LIVEKIT_PUBLISH_TOKEN },
  }),
});
const { session, ingestion } = await createRes.json();
if (!ingestion?.ready) throw new Error("ingestion not ready");

// 2. Connect to the session WebSocket
const ws = new WebSocket(ingestion.url, [`facemode.${ingestion.wsToken}`]);
const pending = new Map();
ws.on("message", (data, isBinary) => {
  if (isBinary) return;
  const msg = JSON.parse(data.toString());
  if (msg.type === "error") console.error("worker error:", msg);
  const resolve = pending.get(msg.type);
  if (resolve) {
    pending.delete(msg.type);
    resolve(msg);
  }
});
const waitFor = (type) => new Promise((resolve, reject) => {
  const timer = setTimeout(() => reject(new Error(`timeout waiting for ${type}`)), 240_000);
  pending.set(type, (msg) => { clearTimeout(timer); resolve(msg); });
});
await new Promise((resolve) => ws.once("open", resolve));

// 3. Negotiate audio format
const started = waitFor("started");
ws.send(JSON.stringify({
  type: "start",
  session_id: session.id,
  audio_encoding: "pcm_s16le",
  sample_rate: 16000,
  channels: 1,
}));
await started;

// 4. Stream one utterance (explicit style shown for clarity)
const pcm = readFileSync("speech-16khz-s16le.pcm");
ws.send(JSON.stringify({ type: "start_utterance", seq: 0 }));
const utteranceEnded = waitFor("utterance_ended");
const chunkSize = 6400; // 200ms of 16kHz s16le mono
for (let offset = 0; offset < pcm.length; offset += chunkSize) {
  ws.send(pcm.subarray(offset, offset + chunkSize), { binary: true });
  await new Promise((r) => setTimeout(r, 200));
}
ws.send(JSON.stringify({ type: "end_utterance", seq: 1 }));
await utteranceEnded;

// 5. Close the socket side, then the REST session
const ended = waitFor("ended");
ws.send(JSON.stringify({ type: "end_session", seq: 2 }));
await ended;
ws.close();

// 200 = finalized, 202 = cleanup pending
await fetch(`${API}/sessions/${session.id}/end`, { method: "POST", headers });
while (true) {
  const s = await (await fetch(`${API}/sessions/${session.id}`, { headers })).json();
  if (s.session?.status === "ENDED") break;
  await new Promise((r) => setTimeout(r, 2000));
}
console.log("session ended");

# pip install requests websockets
import asyncio, json, os, requests, websockets

API = os.environ.get("FACEMODE_API_URL", "https://api.facemode.io/api")
HEADERS = {"x-api-key": os.environ["FACEMODE_API_KEY"]}

# 1. Create the session
created = requests.post(
    f"{API}/sessions",
    headers=HEADERS,
    json={
        "avatarId": os.environ["FACEMODE_AVATAR_ID"],
        "room": {
            "type": "livekit",
            "url": os.environ["LIVEKIT_URL"],
            "token": os.environ["LIVEKIT_PUBLISH_TOKEN"],
        },
    },
).json()
session, ingestion = created["session"], created["ingestion"]
assert ingestion["ready"]

async def wait_for(ws, msg_type, timeout=240):
    async def _loop():
        async for raw in ws:
            if isinstance(raw, bytes):
                continue
            msg = json.loads(raw)
            if msg.get("type") == "error":
                print("worker error:", msg)
            if msg.get("type") == msg_type:
                return msg
    return await asyncio.wait_for(_loop(), timeout)

async def main():
    # 2. Connect to the session WebSocket
    async with websockets.connect(
        ingestion["url"],
        subprotocols=[f"facemode.{ingestion['wsToken']}"],
    ) as ws:
        # 3. Negotiate audio format
        started = asyncio.create_task(wait_for(ws, "started"))
        await ws.send(json.dumps({
            "type": "start",
            "session_id": session["id"],
            "audio_encoding": "pcm_s16le",
            "sample_rate": 16000,
            "channels": 1,
        }))
        await started

        # 4. Stream one utterance (explicit style shown for clarity)
        pcm = open("speech-16khz-s16le.pcm", "rb").read()
        await ws.send(json.dumps({"type": "start_utterance", "seq": 0}))
        chunk = 6400  # 200ms of 16kHz s16le mono
        ended_utt = asyncio.create_task(wait_for(ws, "utterance_ended"))
        for off in range(0, len(pcm), chunk):
            await ws.send(pcm[off:off + chunk])
            await asyncio.sleep(0.2)
        await ws.send(json.dumps({"type": "end_utterance", "seq": 1}))
        await ended_utt

        # 5. Close the socket side, then the REST session
        done = asyncio.create_task(wait_for(ws, "ended"))
        await ws.send(json.dumps({"type": "end_session", "seq": 2}))
        await done

    # 200 = finalized, 202 = cleanup pending
    requests.post(f"{API}/sessions/{session['id']}/end", headers=HEADERS)
    while True:
        s = requests.get(f"{API}/sessions/{session['id']}", headers=HEADERS).json()
        if s.get("session", {}).get("status") == "ENDED":
            break
        await asyncio.sleep(2)
    print("session ended")

asyncio.run(main())