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 Forge Python client (canonical copy)
three_ws_client.py is the single source of truth for the Python wrapper around
the public Forge generation contract (api/forge.js + api/forge-upload.js).
It is stdlib-only (urllib), so it runs unmodified inside Blender's bundled
Python and inside ComfyUI without a pip install into either host.
The Blender add-on, the ComfyUI nodes and the two Modly extensions each vendor a byte-identical copy of this file. Edit the canonical copy here, then re-copy it into every plugin; test_no_drift.py fails the suite if any vendored copy diverges.
Contract wrapped
| Call | Endpoint |
|---|---|
| Text to 3D | POST /api/forge with {prompt, aspect_ratio?, path?, tier?, backend?} |
| Image to 3D | POST /api/forge with {image_urls[], prompt?, path?, tier?, backend?} |
| Poll a job | GET /api/forge?job=<id> returning {status, glb_url?, error?, backend?, ...} |
| Tier/backend/cost matrix | GET /api/forge?catalog |
| Image upload presign | POST /api/forge-upload with {content_type, size_bytes, checksum_sha256?} |
| GLB upload presign | POST /api/scene-glb-upload with {content_type, size_bytes} (200 MB cap) |
| Auto-rig | POST /api/forge?action=rig with {glb_url}, polled on GET /api/forge?job=<id> |
| Remesh | POST /api/forge-remesh with {mesh_url, remesh_mode, operation, target_faces, texture_size, output_format}, polled on GET /api/forge-remesh?job=<id> |
| Publish to an account | POST /api/avatars/upload or /api/avatars/presign, then POST /api/avatars, with a bearer API key carrying avatars:write |
Generation is auth-free (IP rate-limited, scoped to an anonymous client handle
sent as x-forge-client). The geometry path (Meshy/Tripo) is BYOK: pass
provider_key and it travels as the x-forge-provider-key header.
Public API
ThreeWSClient(base_url="https://three.ws", *, provider_key=None, client_handle=None, timeout=30.0)generate_text_to_3d(prompt, *, tier, backend, path, aspect_ratio, on_progress, should_cancel, poll_timeout) -> glb_urlgenerate_image_to_3d(image_bytes, content_type, *, prompt, tier, backend, path, ...) -> glb_urlrig(glb_url, *, on_progress, should_cancel, poll_timeout) -> rigged_glb_urlremesh(mesh_url, *, remesh_mode, operation, target_faces, texture_size, on_progress, should_cancel, poll_timeout) -> result_urlupload_glb(glb_bytes) -> public_url: puts a local GLB where rig and remesh can read itpublish_glb(glb_bytes, *, api_key, name, description, visibility, tags, source_meta) -> avatar, andavatar_page_url(avatar)- Lower-level steps:
submit_text_to_3d(...),submit_image_to_3d(...),submit_rig(glb_url),submit_remesh(mesh_url, ...),upload_image(image_bytes, content_type) -> public_url,poll(job_id, ...) -> glb_url,download(url, dest_path),get_catalog() - Polling retries a 502, 503 or 504 from the poll endpoint instead of failing the job, since a long GPU job outlives the odd gateway hiccup.
ThreeWSError: every failure path raises this with a user-safemessage, a machinecode(needs_key,unconfigured,timeout,cancelled,failed, ...), and the HTTPstatuswhen applicable.content_type_for_path(path): maps.png/.jpg/.jpeg/.webpto the content type Forge accepts, or raises.- Constants mirroring the server:
TIERS,PATHS,BACKENDS,ASPECT_RATIOS(fromapi/_lib/forge-tiers.js), andREMESH_MODES,REMESH_OPERATIONS,REMESH_TEXTURE_SIZES,MAX_SCENE_GLB_BYTES. - HTTPS uses
certifi's CA bundle when it is importable, which fixes certificate errors in hosts whose bundled Python has no system CA store; otherwise the platform default is used.
Example
from three_ws_client import ThreeWSClient, ThreeWSError
client = ThreeWSClient()
try:
glb_url = client.generate_text_to_3d(
"a weathered bronze astrolabe",
tier="standard",
on_progress=lambda status, elapsed: print(f"{status} ({elapsed:.0f}s)"),
)
client.download(glb_url, "astrolabe.glb")
except ThreeWSError as exc:
print(f"generation failed [{exc.code}]: {exc.message}")
Tests
python -m pytest integrations/_pyclient
# or directly:
python integrations/_pyclient/test_three_ws_client.py
python integrations/_pyclient/test_no_drift.py
- test_three_ws_client.py runs a real in-process HTTP server that mimics the Forge contract (no live network) and exercises submit, upload, poll, download, and every error path end to end.
- test_no_drift.py byte-compares the vendored copies in
integrations/blender/three_ws/,integrations/comfyui/three_ws_nodes/,integrations/modly/three-ws/andintegrations/modly/three-ws-publish/against this canonical file and prints the exactcpcommand to fix a drift.
Editing workflow
Change
three_ws_client.pyhere.Copy it over every vendored path:
for d in blender/three_ws comfyui/three_ws_nodes modly/three-ws modly/three-ws-publish; do cp integrations/_pyclient/three_ws_client.py "integrations/$d/three_ws_client.py" doneRun the tests above.