Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

docs(3d-api): correct the endpoint reference and the AI brain tutorial's setup steps

nirholasb2960c7df2f9
diff --git a/data/changelog.json b/data/changelog.json
index 12dd695c4..75d950c6b 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,16 @@
{
"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security. `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-08-15",
+ "title": "Three docs pages stop pointing readers at a dead page, a missing section, and a snippet that does nothing",
+ "summary": "The Vanity page told you to grind a long address yourself in the browser at /vanity, but that path has never existed and answers 404; the in-browser grinder lives at /vanity-wallet, and both links on the page now go there. In Troubleshooting, the fix for a Quick Look model that opens and instantly closes linked to a model-optimization section that is not on the AR page, so the link dropped you at the top with nothing to read; it now opens the section that actually covers it. The same page told you to add a responsive attribute to size an inline embed, with a snippet that set the width in CSS. Neither half worked: responsive sizing is already on by default, and the element reads the width attribute rather than the computed style, so the documented snippet never produced the 3:4 ratio it promised. The instructions now show the form that does work, and name the two things that switch it off.",
+ "tags": [
+ "fix",
+ "docs"
+ ],
+ "link": "/docs/troubleshooting"
+ },
{
"date": "2026-08-15",
"title": "The agent economy volume dashboard stops sending you to profiles that are not there",
diff --git a/docs/3d-api.md b/docs/3d-api.md
index 8ffbc0b51..199eaca16 100644
--- a/docs/3d-api.md
+++ b/docs/3d-api.md
@@ -10,9 +10,10 @@ Base URL: `https://three.ws`
> This page documents the **free** 3D endpoints. Higher-quality generation and
> rigging are paid: **Forge Pro** (quality tiers) at [`/api/x402/forge`](https://three.ws/api/x402/forge)
-> and **Rigged Avatars** (animation-ready skeletons) via `POST /api/forge?action=rig`
-> (POST only, so there is nothing to open in a browser; the catalog link above
-> quotes both).
+> and **Rigged Avatars** (animation-ready skeletons) via `POST /api/forge?action=rig`.
+> The Forge Pro link is a live per-tier price catalog you can open; the rig route
+> is POST-only and quotes its price in the `402` challenge, so there is nothing
+> to browse there.
Prefer a browsable landing page? See [three.ws/3d](https://three.ws/3d) — hero,
live endpoint table, a runnable inspection console, an embedded 3D viewer, and the
diff --git a/docs/tutorials/connect-ai-brain.md b/docs/tutorials/connect-ai-brain.md
index b7ca3d824..b09ed9058 100644
--- a/docs/tutorials/connect-ai-brain.md
+++ b/docs/tutorials/connect-ai-brain.md
@@ -254,12 +254,23 @@ See the [custom skill tutorial](/tutorials/custom-skill) for the full skill-writ
Every chat turn costs tokens. For agents handling real traffic, you need to know where your spend is going.
-The dashboard at [three.ws/my-agents](https://three.ws/my-agents) → your agent → **Usage** tab shows:
+**The per-agent read.** `GET /api/agents/:id/usage` (owner-only) returns that agent's brain usage:
-- **Total tokens** by day, separated into input and output
-- **Estimated cost** at the rate of your selected model
-- **Per-agent breakdown** if you have multiple agents
-- **Top conversations** by token spend (useful for finding runaway prompt loops)
+```js
+const usage = await (await fetch(`/api/agents/${agentId}/usage`, { credentials: 'include' })).json();
+// → {
+// agentId,
+// monthlyQuota, // from the agent's embed policy; null = unlimited
+// currentMonthCalls, // LLM calls this calendar month
+// dailyBreakdown: [{ day, calls }] // last 30 days
+// }
+```
+
+Note what this is and isn't: it counts **calls**, not tokens, and it is the same counter the proxy enforces `monthly_quota` against. It is the number to watch for "is this agent about to hit its cap", not for a dollar figure.
+
+**The account read.** `GET /api/usage/summary` returns your account-level numbers (plan quotas, avatar count and bytes, MCP tool calls in the last 24h, total events in the last 30 days).
+
+**Cost.** The platform prices every call server-side through `api/_lib/llm-pricing.js` and records it, so the spend cap in `checkUserLlmSpendCap` is enforced on real numbers. What there is *not* today is a self-serve token-and-dollar breakdown chart per conversation, nor threshold email alerts. Budget with `monthly_quota` and `rate_limit_per_min` on the embed policy (Step 8) — those are hard, enforced-before-spend limits, which is a stronger control than an after-the-fact alert.
Two specific things to watch:
@@ -267,7 +278,7 @@ Two specific things to watch:
**Tool-call expansion.** A tool that returns 5000 tokens of JSON balloons the next-turn input. If you have a skill that returns large data, summarise the response before it goes back to the model rather than passing the raw payload through.
-For agents handling 1000+ chats per day, you can set up **usage alerts** under **Account → Billing → Alerts**. Pick a threshold (a daily spend or a token count); the platform emails you when you cross it.
+For agents handling real volume, set `monthly_quota` deliberately rather than leaving the 1000-call default: once an agent crosses it the proxy stops serving paid lanes for the rest of the month, which is a blunt but effective ceiling. Pair it with a tight `origins` allowlist so nobody else's site can spend your quota in the first place.
---
@@ -282,13 +293,42 @@ If you have:
<agent-3d agent-id="YOUR_AGENT_ID" id="agent"></agent-3d>
```
-…on a thousand pages, you can switch the brain from Sonnet to Opus to GPT-5.6 Sol entirely from the dashboard. No deploy. No code edit. The next page load picks up the new model.
+…on a thousand pages, you can switch the brain from Sonnet 5 to Opus 5 to GPT-5.6 Sol by changing one field. No deploy. No code edit. The next page load picks up the new model.
+
+That field is `brain.model` on the agent's **embed policy**, read and written at `GET`/`PUT /api/agents/:id/embed-policy`. The `PUT` takes the whole policy document, so read it first, change the one field, and write it back:
+
+```js
+const { policy } = await (await fetch(`/api/agents/${agentId}/embed-policy`, {
+ credentials: 'include',
+})).json();
+
+await fetch(`/api/agents/${agentId}/embed-policy`, {
+ method: 'PUT',
+ headers: { 'Content-Type': 'application/json' },
+ credentials: 'include', // the dashboard's own helper attaches the CSRF token
+ body: JSON.stringify({
+ ...policy,
+ brain: { ...policy.brain, model: 'claude-sonnet-5' },
+ }),
+});
+```
+
+The whole `brain` block is what you tune here:
+
+| Field | Default | What it does |
+|---|---|---|
+| `mode` | `'we-pay'` | `we-pay` uses the platform's credential. `key-proxy` calls your endpoint for a key (Step 9) and requires `proxy_url`. `wallet-gated` and `none` close the lane. |
+| `model` | `'openai/gpt-oss-20b:free'` | The model the agent actually runs, and the ceiling a visitor is clamped to. |
+| `monthly_quota` | `1000` | LLM calls per calendar month before the lane closes. `null` = unlimited. |
+| `rate_limit_per_min` | `10` | Per-minute request cap. |
+
+The `origins` block on the same document is the other half of cost control: with `mode: 'allowlist'` and your own hosts, a request from anywhere else is rejected *before* your model budget is touched. The [/dashboard/api](https://three.ws/dashboard/api) page has an editor for that allowlist.
This makes A/B testing painless. Common patterns:
-- **Cost optimisation pass.** Move a low-stakes agent from Sonnet to Haiku, watch the quality and spend for a week, decide whether to keep the change.
-- **Capability spike.** Promote an agent to Opus for a busy week (a launch, a marketing campaign), then dial back down to Sonnet for steady-state.
-- **Provider failover.** If Anthropic has a brief outage, you can switch the agent to GPT-5.6 Terra in the dashboard and keep traffic moving while you wait. Both keys are stored, both providers are reachable from the same agent record.
+- **Cost optimisation pass.** Move a low-stakes agent from Sonnet 5 to Haiku, watch the quality and spend for a week, decide whether to keep the change.
+- **Capability spike.** Promote an agent to Opus 5 for a busy week (a launch, a marketing campaign), then dial back down to Sonnet 5 for steady-state.
+- **Provider failover.** If one vendor has a brief outage, switch `brain.model` to a peer on another provider and keep traffic moving. You don't have to do this for transient errors, though: the proxy already walks a free-lane fallback chain on a quota/billing/rate-limit failure mid-request.
The trick to making this work cleanly is to write your system prompt in a model-agnostic style. Prompts that lean hard on Claude-specific quirks ("respond in XML tags") can produce slightly different output on GPT. The prompt template in the [agent personality](/tutorials/agent-personality) tutorial is intentionally portable across providers — use that style and your switch-day surprises are minimal.