Docs menu · Python & HTTP API

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.

Python
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
MethodDoes
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.

Python panel (Ctrl+Enter)
# 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.

OpDoes
{"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

MethodPathBody / queryReturns
GET/api/healthEngine version, node count, data folder
GET/api/types?category=All node types with docs, inputs and parameters
GET/api/sceneThe 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/scenesSaved scene files
GET/api/examplesBundled 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/undoUndo in the active project
POST/api/redoRedo in the active project
GET/api/projectsOpen 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/providersDetected 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/stopStop the AI run
GET/api/ai/statusWhether an AI run is active
GET/api/unreal/statusDetected 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:

  • hello with the engine version on connect
  • changed (what, network, node): the scene changed
  • op: every applied op and its result
  • progress (node, frac, msg) during long cooks
  • log (level, text), frame, view
  • ai (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

PowerShell
$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
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\"}"