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.

1.6 KB
Raw Blame

README 3D API

Turns a model URL into a fenced block that GitHub renders as an interactive 3D viewer.

curl -X POST https://three.ws/api/readme-3d \
  -H 'content-type: application/json' \
  -d '{"url":"https://three.ws/avatars/fox.glb","budget":150000}'

Request

Field Type Default Notes
url string required Public https URL of a .glb, .gltf (single file), .obj or .stl. Fetched through the SSRF guard; max 40 MB.
budget number 153600 Target size in bytes of the STL, clamped to 8 KB to 400 KB.
facets number 6000 Upper bound on triangles, 16 to 6000. The budget usually binds first.
name string model Solid name written into the STL.
details boolean false Wrap the block in a <details> disclosure.

Response

{
  "markdown": "```stl\nsolid model\n…\n```\n",
  "facets": 1500,
  "source_facets": 10194,
  "bytes": 214000,
  "github_limit_bytes": 524288,
  "fits_github": true
}

GitHub stops rendering a markdown file larger than 512 KB, so keep the README's total size in mind: npx readme-3d check README.md reports the headroom.

Errors

400 invalid body or blocked URL, 413 source over 40 MB, 415 not a supported model, 422 the file could not be parsed, 429 rate limit (12 per 10 minutes per IP), 502 the model host failed.

The converter is the readme-3d package (convertBytes). In product it is reachable from the Forge download menu, the avatar page, the avatar dashboard, model pages and the /readme-3d page.