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(media-api): document the capabilities endpoint Render Lab is built on, and fix its dead anchor

nirholasc1b83cd9717e
diff --git a/data/changelog.json b/data/changelog.json
index 632fa8d93..1ba9c90e1 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,17 @@
{
"$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-09-09",
+ "title": "Render Lab: every control leads somewhere, and the contact sheet shows its work",
+ "summary": "Render Lab now behaves when the things it depends on do not. The Open image button no longer sits there looking live before a render exists: it reads as unavailable until there is an image, and goes back to unavailable if the render fails. When no featured avatars come back, the model strip explains that and points at the field and at /create instead of showing a blank row. When the pose catalog cannot be reached, the panel says so and offers a retry rather than a lone None chip that reads like the model has no poses. Contact sheet tiles now shimmer while they render, so a sheet in flight looks like it is working instead of like a grid of empty squares, and a tile the renderer could not produce says so and keeps its label. Where a panel is switched off because the model cannot honor it, the explanation and its escape hatch stay at full strength and stay clickable: the link into Rig Doctor was previously unclickable, and the shortcut to a model with a full face rig now finds one from the live catalog instead of loading a raw file the slow way. Dragging the size slider no longer writes a new address on every step, which Safari eventually refuses outright. Copied links now carry the quality setting, so a link really does reopen the exact configuration. Framing, pose and model options are one stop for keyboard and screen reader users and move with the arrow keys, instead of costing 29 tab presses to walk past. The capabilities endpoint the whole page is built on is now documented in the Media API reference, which is where the page has always linked.",
+ "tags": [
+ "fix",
+ "improvement",
+ "docs"
+ ],
+ "link": "/render-lab"
+ },
{
"date": "2026-09-09",
"title": "The retired Flappin UFO page is readable in light mode, and its two bottom-corner controls stopped sitting on top of each other",
diff --git a/docs/media-api.md b/docs/media-api.md
index b35de821e..e02c06a08 100644
--- a/docs/media-api.md
+++ b/docs/media-api.md
@@ -18,6 +18,7 @@ Base URL: `https://three.ws`
|----------|--------|------|--------------|
| [`/api/avatar/render`](#render-an-avatar-as-an-image) | GET | none | Rendered PNG/JPEG/WebP of any public avatar |
| [`/api/render/avatar-clip`](#render-any-glb-posed-and-camera-orbited) | GET, POST | none | Posed, camera-orbited PNG of any GLB |
+| [`/api/avatar/capabilities`](#model-capabilities) | GET | none | What a model can honor: ARKit shapes, skeleton coverage, geometry |
| [`/api/avatar/optimize`](#optimize-a-glb-at-runtime) | GET | none | Runtime GLB transcoder (LOD, textures, morphs, Draco) |
| [`/api/glb`](#same-origin-glb-proxy) | GET | none | Same-origin GLB proxy with open CORS |
| [`/cdn/<key>`](#how-bucket-objects-are-served-cdnkey) | GET, HEAD | none | First-party CDN for bucket objects |
@@ -158,6 +159,109 @@ curl -s -X POST https://three.ws/api/render/avatar-clip \
---
+## Model capabilities
+
+**`GET /api/avatar/capabilities`** answers what a model will and will not honor
+*before* you render it. Every other endpoint here returns a picture; this one
+returns a verdict. It reads the glTF JSON chunk of the GLB (a ranged read of the
+head of the file, never the mesh binary) and reports which ARKit-52 morph
+targets exist, how much of the canonical humanoid skeleton the rig maps onto,
+what the geometry weighs, and a plain-language reason per capability.
+
+It is the same mapping code the renderer and the retargeter run, so it is a
+report of what will happen, not an estimate. Call it once per model and build
+your `expression` and `pose` requests out of shapes and rigs that exist, instead
+of discovering the gap as a still face or a T-pose.
+
+Pass exactly one of `avatar` or `url`. With neither, it returns its own schema,
+so the endpoint is self-documenting from a browser address bar.
+
+### Query parameters
+
+| Name | Type | Notes |
+|------|------|-------|
+| `avatar` | string | three.ws avatar UUID. Public and unlisted avatars only. |
+| `url` | string | Any publicly reachable `.glb` URL. SSRF-guarded and range-capped. |
+
+### Response
+
+`200` with JSON. `x-capabilities-cache` is `hit` or `miss`; responses are
+cacheable for 5 minutes at the client and an hour at the edge.
+
+| Field | Notes |
+|-------|-------|
+| `rig.detected` / `rig.label` | Authoring pipeline inferred from bone names and the glTF generator string. |
+| `rig.boneCount` / `rig.skinCount` | Joints and skins across the whole file. |
+| `rig.canonicalCoverage` | 0..1 share of the canonical humanoid skeleton that maps. Above 0.5 with the core bones present, every baked clip retargets. |
+| `rig.fingerCoverage` | 0..1 share of the finger chain, for poses that need hands. |
+| `rig.mappedBones` / `rig.unmappedBones` | The bones behind those numbers. |
+| `rig.bakedAnimations` | Clips already in the file, by name. |
+| `morphs.total` / `morphs.named` | Morph targets present, including shapes outside the ARKit set. |
+| `morphs.arkitCoverage` | 0..1 share of Apple's 52 facial blendshapes present. |
+| `morphs.supported` / `morphs.missing` | The ARKit names you can drive, and the ones you cannot. |
+| `morphs.visemes` | Viseme shapes present, which is what phoneme-accurate lipsync needs. |
+| `morphs.custom` | Named shapes outside ARKit and the viseme set. |
+| `geometry` | `triangles`, `vertices`, `meshes`, `primitives`, `materials`, `textures`, and the glTF `extensions` in use. |
+| `can.pose` / `can.expression` / `can.lipsync` | `{ supported, reason }`. The reason is written for a human and names the fix when the answer is no. |
+| `subject` | Echoes what was inspected: `{ kind: "avatar", id, name, slug }` or `{ kind: "url", url }`. |
+
+### Errors
+
+| Situation | Response |
+|-----------|----------|
+| Avatar ID not found, or private | `404 not_found` |
+| Avatar exists but has no readable model | `403 private` |
+| `url` is not an absolute http(s) URL | `400 invalid_url` |
+| A caller-supplied `url` could not be read | `400 fetch_failed` |
+| A stored avatar's own model could not be read | `502 fetch_failed` |
+| The file is not a parseable binary glTF 2.0 | `422 not_a_glb` |
+| Over 120 inspections per 10 minutes per IP | `429` with `Retry-After` |
+
+`.gltf` plus external buffers is not supported. Only `.glb`.
+
+### curl
+
+```bash
+# The endpoint's own schema, plus the ARKit-52, viseme, and canonical bone lists
+curl -s https://three.ws/api/avatar/capabilities
+
+# Can this avatar smile? Which shapes can it actually move?
+curl -s 'https://three.ws/api/avatar/capabilities?avatar=a4bad2f5-8a07-43cf-82e5-b6ba1314441e' \
+ | jq '{ expression: .can.expression, shapes: .morphs.supported }'
+
+# Same question about a raw GLB that was never saved as an avatar
+curl -s 'https://three.ws/api/avatar/capabilities?url=https://three.ws/avatars/selfie-girl.glb' \
+ | jq '.can'
+```
+
+### Build a request that cannot silently no-op
+
+```js
+const caps = await fetch(
+ 'https://three.ws/api/avatar/capabilities?avatar=' + avatarId,
+).then((r) => r.json());
+
+const wanted = { mouthSmileLeft: 0.7, mouthSmileRight: 0.7, jawOpen: 0.3 };
+const usable = Object.fromEntries(
+ Object.entries(wanted).filter(([shape]) => caps.morphs.supported.includes(shape)),
+);
+
+const url = new URL('https://three.ws/api/avatar/render');
+url.searchParams.set('avatar', avatarId);
+if (caps.can.pose.supported) url.searchParams.set('pose', 'wave');
+if (Object.keys(usable).length) url.searchParams.set('expression', JSON.stringify(usable));
+
+const res = await fetch(url);
+// 'applied' | 'partial' | 'none': what the renderer could actually drive.
+console.log(res.headers.get('x-render-expression'));
+```
+
+[Render Lab](https://three.ws/render-lab) is this endpoint with a UI on it: it
+reads the report first and switches off the controls the selected model cannot
+honor, with the reason.
+
+---
+
## Optimize a GLB at runtime
**`GET /api/avatar/optimize`** returns a re-encoded variant of a
diff --git a/pages/render-lab.html b/pages/render-lab.html
index 8cf015138..679d0956d 100644
--- a/pages/render-lab.html
+++ b/pages/render-lab.html
@@ -59,9 +59,9 @@
<div class="rl-stage-bar">
<span class="rl-stage-meta" id="stageMeta"></span>
<div class="rl-stage-actions">
- <button type="button" class="rl-btn rl-btn-ghost" id="btnSheet" data-tip="Render this configuration across every camera framing and pose at once. Click any tile to adopt it.">Contact sheet</button>
+ <button type="button" class="rl-btn rl-btn-ghost" id="btnSheet" aria-expanded="false" aria-controls="sheet" data-tip="Render this configuration across every camera framing and pose at once. Click any tile to adopt it.">Contact sheet</button>
<button type="button" class="rl-btn rl-btn-ghost" id="btnPermalink" data-tip="Copy a link that reopens this exact configuration.">Copy link</button>
- <a class="rl-btn rl-btn-primary" id="btnOpen" target="_blank" rel="noopener" data-tip="Open the raw image the API returned, in a new tab.">Open image</a>
+ <a class="rl-btn rl-btn-primary" id="btnOpen" target="_blank" rel="noopener" aria-disabled="true" tabindex="-1" data-tip="Open the raw image the API returned, in a new tab.">Open image</a>
</div>
</div>
</div>
@@ -84,16 +84,16 @@
<section class="rl-code">
<div class="rl-code-head">
<div class="rl-tabs" role="tablist" aria-label="Code format">
- <button type="button" class="rl-tab is-on" role="tab" aria-selected="true" data-lang="url">URL</button>
- <button type="button" class="rl-tab" role="tab" aria-selected="false" data-lang="html">HTML</button>
- <button type="button" class="rl-tab" role="tab" aria-selected="false" data-lang="curl">curl</button>
- <button type="button" class="rl-tab" role="tab" aria-selected="false" data-lang="js">JavaScript</button>
- <button type="button" class="rl-tab" role="tab" aria-selected="false" data-lang="component">Web component</button>
- <button type="button" class="rl-tab" role="tab" aria-selected="false" data-lang="mcp">MCP</button>
+ <button type="button" class="rl-tab is-on" role="tab" aria-selected="true" aria-controls="codePanel" data-lang="url">URL</button>
+ <button type="button" class="rl-tab" role="tab" aria-selected="false" aria-controls="codePanel" data-lang="html">HTML</button>
+ <button type="button" class="rl-tab" role="tab" aria-selected="false" aria-controls="codePanel" data-lang="curl">curl</button>
+ <button type="button" class="rl-tab" role="tab" aria-selected="false" aria-controls="codePanel" data-lang="js">JavaScript</button>
+ <button type="button" class="rl-tab" role="tab" aria-selected="false" aria-controls="codePanel" data-lang="component">Web component</button>
+ <button type="button" class="rl-tab" role="tab" aria-selected="false" aria-controls="codePanel" data-lang="mcp">MCP</button>
</div>
<button type="button" class="rl-btn rl-btn-secondary" id="btnCopyCode">Copy</button>
</div>
- <pre class="rl-code-body"><code id="codeOut"></code></pre>
+ <pre class="rl-code-body" id="codePanel" role="tabpanel" tabindex="0"><code id="codeOut"></code></pre>
<p class="rl-code-note" id="codeNote"></p>
</section>
</section>
@@ -117,7 +117,7 @@
<div class="rl-cap-head" id="capHead"></div>
<div class="rl-meters" id="capMeters"></div>
<ul class="rl-verdicts" id="capVerdicts"></ul>
- <p class="rl-cap-src">Read from the GLB itself via <a href="/docs/media-api#capabilities">/api/avatar/capabilities</a>.</p>
+ <p class="rl-cap-src">Read from the GLB itself via <a href="/docs/media-api#model-capabilities">/api/avatar/capabilities</a>.</p>
</section>
<section class="rl-panel">