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.
three.ws Media & Render API
Free media endpoints for agents and apps built around three.ws 3D assets: server-side avatar rendering, runtime GLB optimization, a CORS-open model proxy, image understanding, speech-to-text, the curated asset libraries, and the photo-input and mesh-processing front doors. Most endpoints here are public and keyless; the two that write to an account say so explicitly.
This page is the companion to the 3D API, which documents the
core free text-to-3D lane (/api/3d/generate), model inspection, and the paid
Forge Pro tiers. Nothing on that page is repeated here: generate a model
there, then render it, optimize it, proxy it, describe it, or save it with the
endpoints below.
Base URL: https://three.ws
| Endpoint | Method | Auth | What it does |
|---|---|---|---|
/api/avatar/render |
GET | none | Rendered PNG/JPEG/WebP of any public avatar |
/api/render/avatar-clip |
GET, POST | none | Posed, camera-orbited PNG of any GLB |
/api/avatar/capabilities |
GET | none | What a model can honor: ARKit shapes, skeleton coverage, geometry |
/api/avatar/optimize |
GET | none | Runtime GLB transcoder (LOD, textures, morphs, Draco) |
/api/glb |
GET | none | Same-origin GLB proxy with open CORS |
/cdn/<key> |
GET, HEAD | none | First-party CDN for bucket objects |
/api/vision |
GET, POST | none | Ask a vision model about an image |
/api/asr |
GET, POST | none | Speech-to-text (voice in) |
/api/avatars/library |
GET | none | Paginated manifest of rigged characters |
/api/objects/library |
GET | none | Paginated manifest of CC0 props |
/api/avatars/from-forge |
POST | session or bearer | Save a generated GLB as your avatar |
/api/input-photo |
POST | none | Vision-validated photo-to-avatar submission |
/api/input-multiview |
POST | none | Vision-validated multi-image reconstruction |
/api/forge-segment |
GET, POST | none | Split a GLB into named parts (async job) |
/api/forge-rembg |
GET, POST | none | Image background removal (async job) |
Render an avatar as an image
GET /api/avatar/render returns a rendered PNG, JPEG, or WebP of any
public or unlisted three.ws avatar. Built for <img> tags, social cards,
partner integrations, and game engine loaders: point an image tag at the URL
and it just works.
Calling it with no parameters returns a self-describing JSON document: every parameter, the scene presets, and the full pose catalog. That response is the machine-readable source of truth for this endpoint.
Query parameters
| Param | Type | Default | Notes |
|---|---|---|---|
avatar |
uuid | required | Avatar ID. Omit it to get the self-describing JSON instead. |
scene |
enum | upper-body |
Camera framing: full-body, upper-body, portrait, headshot. |
size |
integer | 512 |
Square dimension in pixels, 64 to 2048. |
width |
integer | Overrides size for width (64 to 2048). |
|
height |
integer | Overrides size for height (64 to 2048). |
|
bg |
string | transparent |
CSS color or transparent. |
pose |
string | Pose preset ID. Catalog: GET /api/render/avatar-clip. |
|
expression |
json | URL-encoded ARKit-52 morph map, e.g. {"mouthSmile":0.6}. |
|
format |
enum | png |
png, jpeg, or webp. |
quality |
integer | 90 |
1 to 100, for jpeg/webp. |
Response
The first request for a given parameter combination renders via headless
chromium + three.js and returns the image bytes directly
(x-render-cache: miss, plus x-render-scene and x-render-size headers).
The result is cached in object storage keyed on avatar ID, the parameter hash,
and the avatar's updated_at, so editing the avatar busts the cache
automatically. Subsequent requests answer 302 to the CDN copy
(x-render-cache: hit). Both outcomes are correct behind an <img src>.
Errors
| Situation | Response |
|---|---|
| Invalid parameter | 400 with a specific code |
| Avatar does not exist | 404 not_found |
| Avatar is private | 403 private (only public or unlisted avatars render) |
| Over 120 renders per 10 minutes per IP | 429 with Retry-After |
| Render pipeline failed | 502 render_failed |
curl
# Discover the parameters, scenes, and pose catalog
curl -s https://three.ws/api/avatar/render
# The avatar id below is Michelle, a public featured avatar, so these run as-is.
# Swap in your own id from GET https://three.ws/api/avatars/featured or /avatars/<id>.
# Render a 256px transparent portrait
curl -sL -o portrait.png \
'https://three.ws/api/avatar/render?avatar=13f259c7-7024-4d68-b1f0-dbbf52c06209&scene=portrait&size=256&bg=transparent'
# Waving, smiling, as WebP
curl -sL -o card.webp \
'https://three.ws/api/avatar/render?avatar=13f259c7-7024-4d68-b1f0-dbbf52c06209&pose=wave&expression=%7B%22mouthSmile%22%3A0.6%7D&format=webp'
Render any GLB, posed and camera-orbited
POST /api/render/avatar-clip renders a PNG of any public GLB with an
optional pose preset, a free camera orbit, and ARKit-52 facial morphs. Where
/api/avatar/render takes a three.ws avatar ID, this endpoint takes a raw GLB
URL, so it works on models that were never saved as avatars.
GET /api/render/avatar-clip (no body) returns the pose catalog: every
preset's id, label, and group (examples: tpose, apose, wave,
salute, run, sit-chair, thinker, superhero-landing), plus the
cameraOrbit and background value ranges. Fetch it once instead of
hardcoding pose IDs.
Request body (JSON)
| Field | Type | Default | Notes |
|---|---|---|---|
glbUrl |
string | required | Public http(s) URL of the GLB, max 10 MB. SSRF-guarded: private hosts are rejected. |
width |
integer | 1024 |
64 to 2048. |
height |
integer | 1024 |
64 to 2048. |
background |
string | #0a0a0a |
Any CSS color, or transparent. |
posePresetId |
string | A pose ID from the GET catalog. Unknown IDs return 400 unknown_pose. |
|
cameraOrbit |
object | { theta, phi, radius }. theta 0..360 degrees (yaw), phi 0..180 degrees (pitch from top, default 80), radius in meters or null to auto-frame. |
|
expression |
object | ARKit-52 morph map, e.g. { "jawOpen": 0.4, "mouthSmileLeft": 0.6 }. |
Response
200 with image/png bytes. Headers report what was rendered:
x-render-width, x-render-height, x-render-background, and, when a pose
was applied, x-render-pose and x-render-pose-label.
Errors
| Situation | Response |
|---|---|
Missing/non-public glbUrl |
400 bad_request |
| Unknown pose preset | 400 unknown_pose (GET the endpoint for the catalog) |
| Over 60 renders per 10 minutes per IP | 429 with Retry-After |
| Fetch or render failed | 502 render_failed |
curl
# Pose catalog
curl -s https://three.ws/api/render/avatar-clip
# Render a rigged model waving, orbited 30 degrees, on transparent
curl -s -X POST https://three.ws/api/render/avatar-clip \
-H 'content-type: application/json' \
-d '{
"glbUrl": "https://three.ws/avatars/cesium-man.glb",
"posePresetId": "wave",
"cameraOrbit": { "theta": 30, "phi": 80, "radius": null },
"background": "transparent"
}' -o wave.png
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
# 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
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 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
three.ws-hosted GLB tuned for the caller's hardware budget. The pipeline is
lossless or near-lossless (dedup, prune, weld, texture downscale to WebP), so
one source GLB can serve mobile WebGL, desktop WebGL, and VR runtimes without
per-platform asset duplication.
Query parameters
Provide exactly one of src or id; the rest are optional.
| Param | Type | Default | Notes |
|---|---|---|---|
src |
url | Source GLB. Must be on a three.ws-controlled origin (the app origin or the CDN host); anything else is 400 untrusted_source. |
|
id |
uuid | A three.ws avatar ID. Only public or unlisted avatars resolve; private ones return 404. |
|
lod |
enum | 0 |
0 = source, 1 = conservative weld/dedup, 2 = more aggressive weld. |
textureSize |
enum | 2048 |
Max texture edge: 128, 256, 512, 1024, or 2048. Larger textures are downscaled and re-encoded as WebP. |
morphs |
enum | all |
arkit52 drops every morph target not in the ARKit-52 standard set (plus canonical aliases and visemes); all keeps everything. |
draco |
flag | off | draco=1 prefers KHR_draco_mesh_compression, and the client then needs a Draco decoder. It is applied only when it actually shrinks the file (see the size contract below). |
Response
200 with model/gltf-binary bytes, cached immutably (30 days in the
browser, 1 year at the edge, keyed on the full URL).
Size contract
The endpoint never returns more bytes than it was given unless you asked for a
change that genuinely alters the model. Stored three.ws avatars are already
quantized and meshopt-packed, so layering Draco on top of that can easily make a
file bigger; when it does, the endpoint keeps the better encoding (or hands back
the original bytes) instead of honouring the flag into a worse result. The
output declares at most one mesh-compression scheme, never Draco and meshopt
together. Four response headers say exactly what happened, and all four are
listed in access-control-expose-headers so browser fetch() can read them:
| Header | Meaning |
|---|---|
x-three-ws-source-bytes |
Size of the source GLB. |
x-three-ws-output-bytes |
Size of the body you received. |
x-three-ws-optimize |
What the body is: draco, meshopt, none (no mesh compression), or source (the original bytes, returned unchanged because nothing the pipeline produced was smaller). |
x-three-ws-optimize-refused |
draco when draco=1 was requested and dropped because it grew the file. Absent otherwise. |
The one case where the output may exceed the source is a request that really
changed the model: a lod that collapsed vertices, a morphs=arkit52 that
dropped morph targets, or a textureSize that downscaled a texture. There you
asked for different content, so you get it, and the byte headers still report
the exact cost.
Errors
| Situation | Response |
|---|---|
Missing src and id, or invalid lod/textureSize/morphs |
400 invalid_request |
src not on a three.ws origin |
400 untrusted_source |
Source redirected off a three.ws origin, to plain http, or more than 3 times (every hop is re-checked, never followed blindly) |
400 untrusted_src |
| Avatar/upstream not found | 404 source_not_found |
| Source over 50 MB | 413 too_large |
| Source did not answer, or stalled mid-download, within 30 s | 504 source_timeout |
| Upstream fetch failed | 502 upstream_unreachable |
| Transcode pipeline threw | 500 transcode_failed |
Requests are rate-limited per IP; a 429 carries Retry-After.
curl
# Mobile budget: 512px textures, ARKit-52 morphs only
curl -sL -o mobile.glb \
'https://three.ws/api/avatar/optimize?id=13f259c7-7024-4d68-b1f0-dbbf52c06209&textureSize=512&morphs=arkit52'
# By source URL, LOD 1
curl -sL -o lite.glb \
'https://three.ws/api/avatar/optimize?src=https%3A%2F%2Fthree.ws%2Favatars%2Fcesium-man.glb&lod=1'
# Add Draco geometry compression. Smaller bytes, but the client then needs a
# Draco decoder, so only add it when you know the consumer has one.
curl -sL -o mobile-draco.glb \
'https://three.ws/api/avatar/optimize?id=13f259c7-7024-4d68-b1f0-dbbf52c06209&textureSize=512&draco=1'
If draco=1 comes back 500 transcode_failed with draco.createCompressedPrimitive is not a function, that is a server-side codec problem and not something wrong with your request: the running image resolved an older glTF-transform than the one this repo pins, whose Draco writer expects a different encoder interface. Every other parameter still works, so drop draco=1 to get your model now. A rebuild picks up the pinned version and restores it.
Same-origin GLB proxy
GET /api/glb?src=<url> streams any public GLB back with
access-control-allow-origin: *.
When you need it, and when you do not
Since 2026-09-10 you usually do not need it. Every host we serve models from now answers a cross-origin read, so a direct fetch is the default and the proxy is for the cases below. Re-measured 2026-09-10:
| Source host | Cross-origin fetch | Use the proxy? |
|---|---|---|
https://three.ws/... (built-in library avatars, /avatars/*, anything under the site) |
access-control-allow-origin: * on every origin |
No. Fetch it directly. |
https://three.ws/cdn/<key> (the same bucket objects, served first-party) |
access-control-allow-origin: * on every origin |
No. Fetch it directly, and prefer this over the proxy. |
https://pub-*.r2.dev/... (the media bucket's own host: user-generated avatars, forge output, character-library GLBs, the target of /api/avatar/render's 302) |
access-control-allow-origin: * on every origin, since the bucket read rule was opened on 2026-09-10 |
No, not for CORS. Rewriting to /cdn/<key> is still cheaper. |
So a <model-viewer> embed on a partner site, a Jupyter/Colab notebook, a
Codespaces preview, or a Vite dev server on localhost:5173 can now read every
one of those hosts directly. Before that date the bucket host echoed only an
allowlist of origins and silently failed everywhere else, which is the bug most
older embed guides are written around.
The proxy is still the right tool in two cases, and both are about a URL rather than about us:
- A URL on a host that is not ours at all.
/api/glb?src=<url>re-serves any public GLB with open CORS, so a model someone handed you from a third-party CDN loads without you auditing that CDN's headers. - A URL whose host you cannot determine ahead of time. The proxy is harmless on a URL that would have loaded directly, costing one hop on a cold cache and nothing after, so code that accepts arbitrary model URLs can route them all through it and stop branching.
For our own bucket objects, prefer
/cdn/<key> when you have the
object key: same bytes, first-party, CORS-open, and CDN-cached for 30 days at
the edge, which beats both the proxy and the bucket host.
Presigned PUT uploads stay origin-locked on purpose, and that half of the
policy did not change. scripts/set-r2-cors.mjs holds the canonical policy and
node scripts/set-r2-cors.mjs --probe measures what is live from any machine,
with no bucket credentials; see scripts/README.md.
Safe by construction: upstream objects are already public and keyless, and
the fetch runs through the SSRF-hardened fetcher (scheme allowlist, DNS
pinning, private-IP blocklist, redirect re-validation, byte cap, timeout).
The response is always declared model/gltf-binary with nosniff,
content-security-policy: default-src 'none'; sandbox, and
cross-origin-resource-policy: cross-origin, so bytes fetched from a remote
host can never be interpreted as a document on the three.ws origin.
Query parameters
| Param | Type | Notes |
|---|---|---|
src |
url | Required. Public http(s) URL of a .glb. url= is accepted as an alias. |
Response
200 with model/gltf-binary bytes, cached immutably (generated GLBs are
content-addressed, so a given src never changes bytes). Max 30 MB, 20 s
upstream timeout, rate-limited per IP.
Errors
| Situation | Response |
|---|---|
Missing or non-http(s) src |
400 bad_request |
Blocked target (invalid_url, scheme_not_allowed, private_address, host_pin_mismatch) |
400 with that code |
| Upstream over 30 MB | 413 file_too_large |
| Upstream fetch failed | 502 fetch_failed |
curl
curl -sL -o model.glb \
'https://three.ws/api/glb?src=https%3A%2F%2Fthree.ws%2Favatars%2Fcesium-man.glb'
How bucket objects are served (/cdn/<key>)
Every generated asset (avatars, forge output, thumbnails, posters, manifests)
is reachable two ways: from the media bucket's own host, and from
GET https://three.ws/cdn/<key>, which streams the same object through the
site. The first-party path exists because the bucket's public dev host is
rate-limited, and a gallery loading dozens of thumbnails at once gets throttled
there. Both URLs return identical bytes; the /cdn one is CDN-cached and
CORS-open (access-control-allow-origin: *), so it works from any origin
without the proxy above.
Because that path puts bucket content on the same origin as the app, the response is pinned to data rather than a document:
| Rule | Effect |
|---|---|
The Content-Type comes from the object key's extension |
Every write path chooses the extension server-side from an allowlist, so an upstream provider's Content-Type header can never decide what three.ws serves. A stored type is honored only when the extension is unrecognized, and only if it is itself a media type. |
Anything not safe to render inline is sent content-disposition: attachment |
Images (except SVG), glTF/GLB, USDZ, audio, video, and JSON render inline. SVG and unknown types download instead of rendering. |
Every response carries content-security-policy: default-src 'none'; sandbox and x-content-type-options: nosniff |
Anything that does reach a top-level navigation lands in an opaque origin, so it cannot script against three.ws or read its storage. |
None of this affects normal use: <img>, <model-viewer>, <video>, and
fetch() are subresource loads, which ignore content-disposition entirely.
An SVG thumbnail still renders through <img>; what it can no longer do is
open as a page on the site's origin.
Image understanding
POST /api/vision asks a vision model a question about an image and
returns plain text. The same capability powers Forge upload checks and
gallery alt text internally; this is the public HTTP surface. Free-first
provider chain with a paid backstop; the response tells you which provider
answered.
GET /api/vision is a capability probe:
{ configured, imageTypes }. Use it to decide whether to offer
describe/critique affordances before uploading anything.
Request
Two transports:
| Transport | How |
|---|---|
| Raw bytes | Body is the image; Content-Type must be image/jpeg, image/png, image/webp, or image/gif. Max 12 MB. |
| JSON | { "image": "<base64 or data URI>", "imageUrl": "...", "prompt": "...", "maxTokens": 512, "imageType": "image/png" }. Provide image or imageUrl (a public https URL; SSRF-guarded). imageType labels a bare base64 image when it is not a data URI. |
prompt and maxTokens can also ride as query parameters on either
transport. prompt defaults to a concise two-sentence description and is
capped at 2000 characters; maxTokens is clamped to 16..2048 (default 512).
Rate limits are per user when signed in (session cookie or bearer token) and per IP otherwise; signing in raises the budget.
Response
{ "text": "A low-poly bronze knight in a T-pose, brushed-metal armor...", "provider": "nvidia", "model": "..." }
Errors
| Situation | Response |
|---|---|
| No image in the request | 400 bad_request |
Unsupported raw Content-Type |
415 unsupported_media_type |
| Image over 12 MB | 413 payload_too_large |
Bad imageUrl |
400 invalid_image_url |
| No vision provider configured | 503 not_configured |
| All providers failed | 502 with the upstream code |
curl
# Capability probe
curl -s https://three.ws/api/vision
# Raw bytes with a custom question
curl -s -X POST 'https://three.ws/api/vision?prompt=What%20object%20is%20this%3F' \
-H 'content-type: image/png' \
--data-binary @render.png
# By URL
curl -s -X POST https://three.ws/api/vision \
-H 'content-type: application/json' \
-d '{"imageUrl":"https://three.ws/logo.png","prompt":"Describe this image in one sentence."}'
Speech-to-text
POST /api/asr transcribes a spoken utterance. It is the voice-in
companion to POST /api/tts/speak (voice out), and exists so users can talk
to an avatar with a real cross-browser recognizer instead of the Chrome-only
webkitSpeechRecognition. The lane is NVIDIA Riva ASR; there is deliberately
no paid backstop, so when it is unconfigured clients keep their browser
fallback.
GET /api/asr is a capability probe:
{ configured, encodings, sampleRate }. sampleRate is 16000, the Riva
acoustic-model rate clients should downsample to.
Request
Two transports, max 8 MB of audio either way:
| Transport | How |
|---|---|
| Raw bytes | Body is the audio; Content-Type picks the codec: audio/wav (header parsed, rate taken from the file), audio/pcm or audio/L16 (raw 16-bit LE PCM; set ?rate=), audio/flac, audio/ogg (Opus). WebM/Opus is rejected with 415: decode it to PCM/WAV client-side first. |
| JSON | { "audio": "<base64>", "format": "wav", "language": "en-US", "sampleRate": 16000, "words": true, "model": "..." }. format is one of wav, pcm, flac, ogg (default wav). |
Query parameters work on either transport: language (BCP-47, default
en-US), rate (PCM sample rate; defaults to 16000 when the audio does not
declare one), words=1 (word-level timestamps), model (override the Riva
model name).
Rate limits mirror /api/vision: per user when signed in, per IP otherwise.
Response
{ "text": "make the avatar wave", "confidence": 0.94, "language": "en-US", "model": "...", "durationSec": 1.8 }
With words=1 the response adds a words array of word-level timestamps.
Errors
| Situation | Response |
|---|---|
Unsupported audio Content-Type (including WebM) |
415 unsupported_media_type |
| Audio over 8 MB | 413 payload_too_large |
| No audio bytes | 400 bad_request |
| Riva rejected the input | 400 invalid_argument |
| Lane not configured | 503 not_configured |
| Upstream failure | 502 provider_error |
curl
# Capability probe
curl -s https://three.ws/api/asr
# Transcribe a WAV with word timestamps
curl -s -X POST 'https://three.ws/api/asr?words=1' \
-H 'content-type: audio/wav' \
--data-binary @speech.wav
Character library
GET /api/avatars/library returns the curated rigged character library:
professionally rigged humanoid GLBs (Y Bot, X Bot, Warrok, Remy, zombies,
knights, plus CC0 sets like Quaternius and KayKit). Every GLB carries a
skeleton, skin weights, and textures, so it drops straight into the pose
studio, widget studio, or embed viewer and drives the whole canonical
animation clip library via retargeting. No auth, no key.
The GLBs live on the CDN; this endpoint serves a small manifest whose entries carry absolute CDN URLs the browser loads directly (CDN CORS allows GET from web origins).
Query parameters
Pagination is opt-in and backward compatible:
| Param | Type | Notes |
|---|---|---|
limit |
integer | 1 to 1000. Omit it entirely to get the whole library in one response. |
offset |
integer | Starting index, default 0. Only meaningful with limit. |
Response
{
"avatars": [
{
"name": "y-bot",
"label": "Y Bot",
"url": "https://<cdn>/avatars/mixamo/glb/y-bot.glb",
"thumb": "https://<cdn>/avatars/mixamo/thumbs/y-bot.png",
"bytes": 3145728,
"skins": 1,
"animations": 1,
"source": "mixamo",
"license": "Mixamo"
}
],
"total": 107,
"generated_at": "2026-07-01T00:00:00.000Z"
}
thumb is present when a thumbnail has been rendered. With limit the
response adds offset and next_offset (null on the last page); total
is always the full library size. Before the manifest is staged the endpoint
returns { "avatars": [], "total": 0 }, so feature-detect by emptiness, not
by error handling. Responses are edge-cached for 5 minutes.
curl
# Whole library
curl -s https://three.ws/api/avatars/library
# Page of 24
curl -s 'https://three.ws/api/avatars/library?limit=24&offset=0'
Object library
GET /api/objects/library is the same manifest pattern for the CC0 3D
prop library: free, commercial-OK objects (Poly Haven and other CC0 sources)
staged as web-ready GLBs. Same pagination (?limit=1..1000, ?offset=),
same empty-until-staged behavior, no auth. One difference from the character
library: this endpoint validates the cursors strictly, so a malformed
?limit/?offset returns 400 invalid_limit / 400 invalid_offset instead
of being coerced into a page. The manifest is served with
access-control-allow-origin: *, so a studio embedded on another origin can
render the object tray from it (the objects themselves already load cross-origin
through /cdn/<key>). See the object library doc
for the full parameter table.
Response
{
"objects": [
{
"name": "wooden-crate",
"label": "Wooden Crate",
"url": "https://<cdn>/objects/polyhaven/glb/wooden-crate.glb",
"thumb": "https://<cdn>/objects/polyhaven/thumbs/wooden-crate.png",
"bytes": 1048576,
"categories": ["props"],
"tags": ["wood", "container"],
"license": "CC0",
"source": "polyhaven"
}
],
"total": 511,
"generated_at": "2026-07-01T00:00:00.000Z"
}
With limit, the response adds offset and next_offset exactly like the
character library.
curl
curl -s 'https://three.ws/api/objects/library?limit=12'
Save a generated GLB into your library
POST /api/avatars/from-forge saves a generated GLB (by URL) straight
into the caller's avatar library, server-side. This is the durable end of the
text-to-3D-avatar pipeline: forge a mesh (see the 3D API), rig
it, then hand the final URL here. Doing the copy server-side sidesteps
cross-origin reads of provider URLs and browser upload caps, and routes
through the same avatar-creation path as a normal upload, so the result is a
first-class avatar with its own agent.
Auth required: a signed-in session cookie, or a bearer token carrying the
avatars:write scope. Everything else on this page is public; this endpoint
writes to your account.
Request body (JSON)
| Field | Type | Default | Notes |
|---|---|---|---|
glb_url |
string | required | Public https URL of the GLB. SSRF-guarded; max 64 MB. |
name |
string | required | Avatar name, 1 to 80 characters. |
visibility |
enum | unlisted |
public, unlisted, or private. |
source_prompt |
string | The prompt that generated it, kept as provenance (max 1000 chars). | |
rigged |
boolean | Provenance only. The server inspects the GLB itself for the real rig state; this flag never decides anything. | |
tags |
string[] | Up to 20 organizing tags. |
The server fetches the GLB, validates the binary glTF header, copies it into your storage namespace, registers the avatar, provisions its agent, and, when the mesh arrived static, queues an auto-rig so the avatar can animate.
Response
201 with { "avatar": { ... }, "view_url": "https://three.ws/avatars/<id>" } (the avatar detail page, the canonical link target across the platform).
Errors
| Situation | Response |
|---|---|
| Not signed in / missing scope | 401 unauthorized |
Missing glb_url or name |
400 invalid_request |
| Non-public or non-https URL | 400 invalid_url |
| URL did not return a valid GLB | 422 invalid_glb |
| GLB over 64 MB | 413 payload_too_large |
| Upstream fetch failed | 502 fetch_failed |
| Too many saves | 429 rate_limited with Retry-After |
curl
curl -s -X POST https://three.ws/api/avatars/from-forge \
-H 'authorization: Bearer YOUR_TOKEN' \
-H 'content-type: application/json' \
-d '{
"glb_url": "https://three.ws/cdn/forge/anon/a1b2c3d4.glb",
"name": "Bronze Knight",
"visibility": "public",
"source_prompt": "a bronze knight in ornate armor",
"tags": ["knight", "fantasy"]
}'
Photo to avatar
POST /api/input-photo is the vision-validated front door for turning a
photo into an avatar. It checks that the image actually contains a face (so a
landscape or a text screenshot fails fast with guidance instead of burning a
generation slot), then submits it to the forge pipeline as an
image-conditioned generation with an avatar-optimized prompt, ready for
auto-rigging. No auth; rate-limited per IP on the generation bucket.
Privacy is transient by default. The source photo is never stored in the
creation log unless you set privacy_opt_in: true, and when you pass the
storage_key from /api/forge-upload, the uploaded object is deleted from
storage as soon as the generation job is created. No image bytes are written
to application logs.
Request body (JSON)
| Field | Type | Default | Notes |
|---|---|---|---|
image_url |
string | required | Public https URL of the photo, max 2048 characters. |
storage_key |
string | The storage key returned by /api/forge-upload, enabling the transient delete. |
|
privacy_opt_in |
boolean | false |
true keeps the photo as the creation's preview image. |
tier |
enum | standard |
draft, standard, or high. |
skip_face_check |
boolean | false |
Bypass the face-presence gate (for stylized or partial inputs). |
Response
200 with the forge job fields (job_id, creation_id, and the rest of the
standard /api/forge submission response) plus:
{
"mode": "photo_to_avatar",
"auto_rig": true,
"privacy_retained": false,
"privacy_note": "Your photo was processed transiently and was not stored. ..."
}
Poll the job on /api/forge?job=<job_id> like any forge generation.
Errors
| Situation | Response |
|---|---|
Missing/invalid image_url |
400 invalid_image_url |
| No face detected | 422 face_not_detected, with a reason and an override hint (skip_face_check: true) |
| Generation service unreachable | 502 generation_unreachable |
| Forge rejected the submission | Forge's own status and error code, passed through |
| Rate limit | 429 with Retry-After |
When the vision lane is unconfigured or errors, the face check fails open and
the submission proceeds; forge still validates the image. The hand-off to
/api/forge is bounded to 30 seconds and is deliberately never retried, since
that POST enqueues a generation and a replay would queue (and bill) a second
job; a hang there surfaces as 502 generation_unreachable rather than an
endpoint that never answers.
curl
curl -s -X POST https://three.ws/api/input-photo \
-H 'content-type: application/json' \
-d '{"image_url":"https://three.ws/avatars/thumbs/default.png","tier":"standard"}'
Multi-view reconstruction
POST /api/input-multiview accepts 2 to 6 photos of one object from
different angles, validates each with vision (clear subject? in focus? not a
text screenshot?), and submits them to the forge pipeline as a multi-view
reconstruction job. The validation step catches mismatched images and blank
uploads before a generation slot is spent. Same transient-by-default privacy
policy as /api/input-photo. No auth; rate-limited per IP.
Request body (JSON)
| Field | Type | Default | Notes |
|---|---|---|---|
image_urls |
string[] | required | 2 to 6 public https URLs, each max 2048 characters. Extras beyond 6 are dropped. |
storage_keys |
string[] | Storage keys from /api/forge-upload, deleted after submission unless opted in. |
|
prompt |
string | Optional guidance text, max 1000 characters. | |
tier |
enum | standard |
draft, standard, or high. |
privacy_opt_in |
boolean | false |
true keeps the photos as preview images. |
skip_validation |
boolean | false |
Bypass the per-image vision check. |
Response
200 with the forge job fields plus a per-image validation array,
privacy_retained, and privacy_note:
{
"job_id": "f1.eyJ...",
"validation": [
{ "url": "https://example.com/front.jpg", "index": 0, "ok": true, "subject": "ceramic robot figurine" },
{ "url": "https://example.com/back.jpg", "index": 1, "ok": true, "subject": "ceramic robot figurine" }
],
"privacy_retained": false,
"privacy_note": "Your photos were processed transiently and were not stored. ..."
}
Errors
| Situation | Response |
|---|---|
| Fewer than 2 usable URLs | 400 too_few_images |
| One or more images failed validation | 422 invalid_views, with the full validation array (each failure carries an issue such as no_subject, text_screenshot, too_dark_or_blurry, or abstract_or_diagram, and an actionable message) plus an override hint (skip_validation: true) |
| Generation service unreachable | 502 generation_unreachable |
| Rate limit | 429 with Retry-After |
As with /api/input-photo, the hand-off to /api/forge is bounded to 30
seconds and never retried, so the same photos can never be queued twice.
curl
curl -s -X POST https://three.ws/api/input-multiview \
-H 'content-type: application/json' \
-d '{
"image_urls": [
"https://example.com/owl-front.jpg",
"https://example.com/owl-side.jpg",
"https://example.com/owl-back.jpg"
],
"tier": "high"
}'
Split a GLB into named parts
POST /api/forge-segment splits a 3D model into named, addressable parts
(an async job: submit, then poll). Useful for turning a monolithic generated
mesh into components you can recolor, swap, or animate independently. No
auth; rate-limited per IP.
Request body (JSON)
| Field | Type | Default | Notes |
|---|---|---|---|
mesh_url |
string | required | Public https URL of the mesh: GLB, GLTF, OBJ, STL, PLY, OFF or DAE. SSRF-validated server-side. FBX is refused (see Errors). |
method |
enum | auto |
auto, connected (connected components), or crease (split at hard edges). |
max_parts |
integer | 24 |
2 to 64. |
min_part_faces |
integer | 64 |
4 to 100000. Parts smaller than this are merged. |
crease_angle |
number | 40 |
5 to 170 degrees, for the crease method. |
only_part |
string | Export just this part id or name (e.g. part_03). |
Response
202 with { "job_id": "...", "status": "queued", "method": "auto", "eta_seconds": 30 }.
GET /api/forge-segment?job=<id> polls the job:
{
"job_id": "...",
"status": "done",
"result_url": "https://.../segmented.glb",
"manifest_url": "https://.../parts.json",
"parts": [ { "...": "one entry per part" } ],
"part_count": 12,
"source_faces": 48210,
"method": "auto",
"warnings": null,
"error": null
}
Fields are null until the stage that produces them completes; on failure
status reflects it and error carries the reason.
Errors
| Situation | Response |
|---|---|
Missing/non-public mesh_url |
400 invalid_mesh_url |
mesh_url names an .fbx file |
400 unsupported_mesh_format; convert it to GLB with /api/forge-remesh ("operation":"convert","output_format":"glb") first |
Malformed ?job= |
400 invalid_job (missing entirely: 400 missing_job) |
| Worker not deployed on this environment | 503 unconfigured |
| Worker rejected the job | 502 segment_failed |
| Worker unreachable while polling | 502 segment_status_failed |
| Rate limit | 429 with Retry-After |
A poll that answers 502 segment_status_failed carries no status field, so a
polling client should keep polling: the worker was briefly unreachable, which is
not the same as the job dying.
curl
# Submit
curl -s -X POST https://three.ws/api/forge-segment \
-H 'content-type: application/json' \
-d '{"mesh_url":"https://three.ws/avatars/cesium-man.glb","method":"auto","max_parts":16}'
# Poll
curl -s 'https://three.ws/api/forge-segment?job=JOB_ID'
Background removal
POST /api/forge-rembg removes the background from an image (an async
job: submit, get 202, poll). It exists for the forge pipeline (clean
subject cutouts reconstruct better), but it is a general-purpose endpoint. No
auth; rate-limited per IP.
Request body (JSON)
| Field | Type | Default | Notes |
|---|---|---|---|
image_url |
string | required | Public https URL of the image. SSRF-validated server-side. |
model |
enum | rmbg2 |
rmbg2, u2net, isnet, u2net_human_seg, or silueta. |
Response
202 with { "job_id": "...", "status": "queued", "eta_seconds": 10 }.
GET /api/forge-rembg?job=<id> polls the job:
{ "job_id": "...", "status": "done", "result_url": "https://.../cutout.png", "error": null }
Errors
| Situation | Response |
|---|---|
Missing/non-public image_url |
400 invalid_image_url |
Malformed ?job= |
400 invalid_job (missing entirely: 400 missing_job) |
| Worker not deployed on this environment | 503 unconfigured |
| Worker rejected the job | 502 rembg_failed |
| Worker unreachable while polling | 502 rembg_status_failed |
| Rate limit | 429 with Retry-After |
A poll that answers 502 rembg_status_failed carries no status field, so a
polling client should keep polling: the worker was briefly unreachable, which is
not the same as the job dying.
curl
# Submit
curl -s -X POST https://three.ws/api/forge-rembg \
-H 'content-type: application/json' \
-d '{"image_url":"https://three.ws/avatars/thumbs/default.png","model":"rmbg2"}'
# Poll
curl -s 'https://three.ws/api/forge-rembg?job=JOB_ID'
Related
- 3D API - the core free text-to-3D lane, model inspection, and the paid Forge Pro tiers
- Image to 3D - the photo-input reconstruction product these front doors feed
- Voice Lab - voice cloning and synthesis, the other half of the avatar voice loop
- API Reference - the full three.ws HTTP API surface