# Rosto

> Turn one consenting selfie into a living, emotionally-rich avatar that animates
> in any browser — breathing, blinking, speaking (viseme lip-sync) and expressing
> a full range of genuine emotion, with no AI at runtime.

Rosto is an API plus an embeddable browser rig. You create an avatar once (a
model stylizes the photo and builds a QA-gated FACS expression set), then the
served runtime animates it live in any browser. There are no model calls while
the avatar plays.

## Start here
- Console (bring a face to life in a browser): https://app.rosto.ai
- API base: https://studio.rosto.ai
- MCP server for agents (JSON-RPC, streamable HTTP): https://mcp.rosto.ai/mcp
- OpenAPI: https://studio.rosto.ai/openapi.json  (interactive: https://studio.rosto.ai/docs)
- Quickstart: https://studio.rosto.ai/docs-site
- Avatar Package spec (the portable format, self-host + agent integration): https://studio.rosto.ai/docs-site/avatar-package

## Embed an existing avatar (a public token is the capability)
<div id="rosto"></div>
<script src="https://studio.rosto.ai/rig/avatar-rig.js"></script>
<script>
  fetch("https://studio.rosto.ai/pub/PUBLIC_TOKEN/manifest.json").then(r => r.json()).then(m => {
    const rig = AvatarRig.mount(document.getElementById("rosto"), m, {size: 320});
    rig.setState("idle");            // idle · listening · thinking · speaking
    // rig.speak("Hello!"); rig.express("genuine-joy"); rig.setMood("warm");
  });
</script>

## Create via the API
Authenticate with `x-api-key`. Get a key from the Console (redeem an invite).
1. POST https://studio.rosto.ai/v1/avatars
   body: {"image_base64": "<jpeg/png/webp>", "mime_type": "image/jpeg", "consent_attested": true}
   -> {"avatar": {"id": "...", "public_token": "..."}}
   (consent_attested MUST be true; the photo is kept encrypted only until the avatar is accepted, then deleted)
2. POST https://studio.rosto.ai/v1/avatars/<id>/frames        (build the expression set; may be async)
3. GET  https://studio.rosto.ai/pub/<public_token>/manifest.json   (the runtime loads this)
4. GET  https://studio.rosto.ai/v1/avatars/<id>/export             (download a standalone, self-hostable ZIP: portable manifest + base + frames + rig + runnable index.html + README + AGENTS.md; requires manage scope + an approved avatar)

## Drive the rig (no AI at runtime)
rig.setState("idle"|"listening"|"thinking"|"speaking"|"acknowledging")
rig.setMood(mood); rig.express(emotion); rig.speak(text)
rig.command({...}) / rig.play([...])   — a JSON command stream can drive it automatically
The manifest lists the emotions a given avatar supports.

## MCP tools (for agents)
POST https://mcp.rosto.ai/mcp  (JSON-RPC 2.0)
- start_free(invite_code) -> api_key
- create_avatar(api_key, image_base64, mime_type, consent) -> avatar_id, public_token
- build_frames(api_key, avatar_id)
- preview(public_token)
- get_embed_guide(public_token)
- get_credits(api_key) / buy_credits(api_key)

## Invariants (always true)
- Consent is required for every avatar; the consent record is kept even after deletion.
- The uploaded photo is kept encrypted only until the avatar is accepted, then permanently deleted.
- No AI at runtime: the playing avatar is a pure browser rig.
- Public tokens are revocable to the CDN edge (rotate or delete).
- AI-generated media is provenance-stamped (IPTC digitalSourceType: trainedAlgorithmicMedia).