Documentation
Python & HTTP API
Overview
Everything the AI does goes through a public, local API, so you can do it too. While Tessera (or a headless engine) is running, the engine listens on http://127.0.0.1:7419, localhost only. All requests and responses are JSON; errors return {"ok": false, "error": "..."}. Node references accept "graph/node" or a bare name in the current graph (or the op’s network).
Python client
tessera.client is a tiny standard-library client. Use the engine’s own Python, or copy client.py from %LOCALAPPDATA%\Programs\tessera\resources\engine\tessera next to your script.
from tessera.client import Tessera
t = Tessera() # http://127.0.0.1:7419
t.add("grid", "ground", size=[50, 50], rows=100, cols=100)
t.add("mountain", "hills", inputs=["ground"], height=4, element_size=12)
print(t.cook()) # summary + errors of the display node
t.set("hills", height="=4 + sin(F*0.1)") # any param can be an expression
t.render(view="persp", file="hills.png") # PNG bytes, also written to file
t.export("hills", "C:/temp/hills.glb")
t.save("hills") # -> %USERPROFILE%\Tessera\scenes\hills.tsr| Method | Does |
|---|---|
Tessera(url, network=None) | Connect; network sets the default graph for ops |
add(type, name, inputs, network, **params) | Add a node, returns its name |
set(node, **params) | Set parameters |
connect(src, dst, index) | Wire nodes |
display(node) | Set the display flag |
ops(list) | Send raw ops; raises on any failed op |
cook(path, frame) | Cook report |
render(path, view, file, **kw) | PNG bytes (optionally saved) |
export(path, file, **kw) | Write geometry files |
scene(), types() | Scene state, node catalogue |
python(code) | Run code in the engine |
new(), save(file), load(file) | Scene files |
Python panel and run_python
The Python tab in the app, POST /api/python and the MCP tool run_python run code inside the engine with these names ready: scene (the active project’s Scene), tessera, np, Geometry, ops(list), add(type, name, inputs, **params), cook(path, frame) and render(path, **kw). A single expression returns its value; otherwise set result. Printed output is returned too.
# 25 houses in a grid, each with its own seed
for i in range(25):
add("fairy_house", f"house_{i}", style="random", seed=i,
translate=[(i % 5) * 14, 0, (i // 5) * 14])
ops([{"op": "add", "type": "merge", "name": "street",
"inputs": [f"house_{i}" for i in range(25)], "display": True},
{"op": "layout"}])
result = cook().summary()Graph ops
POST /api/ops with {"ops": [...]} applies ops in order (one undo step per request). Each op may carry "network" to target a graph other than the current one.
| Op | Does |
|---|---|
{"op":"add","type":"box","name":"b","params":{...},"inputs":["src"],"network":"main","display":true} | Add a node. Nodes added with inputs become the display node by default. |
{"op":"set","node":"b","params":{...}} | Set parameters (values or "=expressions") |
{"op":"reset","node":"b","param":"size"} | Reset one parameter to its default |
{"op":"connect","src":"a","dst":"b","index":0} | Wire a into input index of b |
{"op":"disconnect","node":"b","index":0} | Remove the wire into an input |
{"op":"delete","node":"b"} | Delete a node (downstream reconnects to its first input; "reconnect":false to skip) |
{"op":"rename","node":"b","to":"c"} | Rename |
{"op":"display","node":"b"} | Set the display flag |
{"op":"bypass","node":"b","value":true} | Bypass on or off |
{"op":"comment","node":"b","text":"why"} | Comment shown under the node |
{"op":"move","node":"b","pos":[x,y]} | Position in the graph editor |
{"op":"network","name":"body","doc":"..."} | Create a graph (network) |
{"op":"current","network":"main"} | Switch the current graph |
{"op":"delete_network","name":"body"} | Delete a graph |
{"op":"layout","network":"main"} | Auto layout |
{"op":"frame","frame":24} | Set the current frame |
{"op":"settings","fps":24,"frame_range":[1,240]} | Frame rate and range |
{"op":"clear_sim","node":"sim"} | Clear a simulation cache |
{"op":"clear_cache"} | Clear all cook caches |
{"op":"stash","source":"node","name":"baked"} | Bake a node’s current output into a stash node |
Parameter values may be expressions: "=sin(F*0.1)" (F frame, T seconds, ch("node.param")). Unknown parameter names are rejected, so check /api/types or the node reference.
HTTP endpoints
| Method | Path | Body / query | Returns |
|---|---|---|---|
| GET | /api/health | Engine version, node count, data folder | |
| GET | /api/types | ?category= | All node types with docs, inputs and parameters |
| GET | /api/scene | The active project: fps, frame, frame range, current graph, all graphs with nodes, params, inputs, flags, errors | |
| POST | /api/ops | {ops:[...]} | Apply graph ops in order; returns per-op results and all_ok |
| POST | /api/cook | {path?, frame?, network?} | Cook a node: geometry summary, node errors and warnings, time |
| GET | /api/geo | ?path=&frame= | Triangulated display buffers (base64) for meshes, lines, points, volumes |
| GET | /api/attribs | ?path=&owner=&start=&count=&frame= | Spreadsheet rows (owner point, prim, vertex or detail) |
| POST | /api/python | {code} | Run Python in the engine; returns stdout and result |
| POST | /api/render | {path?, frame?, view, width, height, azimuth, elevation, wireframe} | Software render as base64 PNG (also saved to renders/last.png) |
| POST | /api/export | {path?, file, frame?, frame_start?, frame_end?} | Write geometry files; returns the file list |
| POST | /api/lint | {path?} | Layout check report (overlaps, floating parts, roofs, chimneys) |
| POST | /api/scene/new | {name?} | New project tab |
| POST | /api/scene/save | {file?} | Save the active project (.tsr); bare names go to scenes/ |
| POST | /api/scene/load | {file} | Open a .tsr in a new tab |
| GET | /api/scenes | Saved scene files | |
| GET | /api/examples | Bundled examples with titles and descriptions | |
| POST | /api/examples/load | {name} | Open an example in a new tab |
| POST | /api/recipes/save | {title?, description?} | Save the active project as a recipe for the local AI |
| POST | /api/undo | Undo in the active project | |
| POST | /api/redo | Redo in the active project | |
| GET | /api/projects | Open projects and the active one | |
| POST | /api/projects/new | {name?} | New project |
| POST | /api/projects/switch | {id} | Switch the active project |
| POST | /api/projects/close | {id} | Close a project tab |
| POST | /api/projects/rename | {id, name} | Rename a project |
| POST | /api/view | {frame_all? | azimuth, elevation, distance, target} | Move the camera in connected windows |
| GET | /api/history | ?limit= | Recent ops with results |
| GET | /api/ai/providers | Detected AI providers and models | |
| POST | /api/ai/ask | {provider, prompt, new_session?, model?} | Start an AI run (provider local, claude or gpt); progress streams over the WebSocket |
| POST | /api/ai/stop | Stop the AI run | |
| GET | /api/ai/status | Whether an AI run is active | |
| GET | /api/unreal/status | Detected Unreal editors, bound project, links, last result | |
| POST | /api/unreal/send | {path?, asset?, spawn?} | Send a node to Unreal |
| POST | /api/unreal/live | {live, path?, asset?} | Turn live link on or off |
| POST | /api/unreal/unlink | {asset} | Remove one linked asset |
| POST | /api/unreal/target | {id} | Bind the link to another open editor |
WebSocket events
Connect to ws://127.0.0.1:7419/ws to follow everything live. The server sends JSON messages:
hellowith the engine version on connectchanged(what,network,node): the scene changedop: every applied op and its resultprogress(node,frac,msg) during long cookslog(level,text),frame,viewai(event: start, text, tool, tool_result, done, error)unreal/unreal_state: Unreal link results and state
Geometry model
Inside the engine (Python panel, attrib_wrangle, python node) geometry uses these conventions: g.P is an (N, 3) array of points; point, primitive, vertex and detail attributes are dicts of numpy arrays (N, Cd 0..1, pscale, v, orient, uv, name…); primitives are closed polygons or open polylines; groups are boolean masks; g.volumes holds fog or SDF grids and g.heightfield the terrain layers. Y is up and 1 unit is 1 metre.
Calling it from anything
$ops = '{"ops":[{"op":"add","type":"torus","name":"ring"},{"op":"add","type":"subdivide","name":"OUT","inputs":["ring"]}]}'
Invoke-RestMethod -Method Post -Uri http://127.0.0.1:7419/api/ops -ContentType 'application/json' -Body $ops
Invoke-RestMethod -Method Post -Uri http://127.0.0.1:7419/api/export -ContentType 'application/json' -Body '{"path":"OUT","file":"~/Tessera/exports/ring.glb"}'curl -s http://127.0.0.1:7419/api/health
curl -s -X POST http://127.0.0.1:7419/api/cook -H "Content-Type: application/json" -d "{\"path\":\"OUT\"}"