The HTTP service that OSHUN_TRELLIS_3D_URL points at — the missing server for
the trellis-provider.ts client (a prior self-audit found the client had no
in-repo implementation, so the "open" 3D path resolved a client with nothing
answering it). This service does not re-implement TRELLIS: it wraps the
already-real CLI runner libs/isis/3d-inference-local/src/models/ trellis2_image_to_3d_runner.py, tracks async tasks, and serves the mesh.
Contract (matched to trellis-provider.ts)#
| Method | Path | Response |
|---|---|---|
POST |
/generate |
{ success, task_id, estimated_time } |
GET |
/task/{id} |
{ data: { task_id, status, progress, stage?, output?, metrics?, error? } } |
POST |
/upload (multipart file) |
{ image_token } |
GET |
/health |
{ status, gpu_available, model_loaded, version } |
GET |
/files/{id}/{name} |
the rendered mesh bytes (what mesh_url points at) |
status ∈ pending | processing | generating_sparse | generating_slat | complete | failed.
The client polls /task/{id} until complete (with output.mesh_url) or failed.
Honest limits#
- Image-to-3D only. The wrapped runner is single-image;
mode:"text"fails loud (422).multi_imageuses the first view. - Geometry (obj/ply), not textured glb. The runner emits geometry; the
service maps the requested format onto obj/ply and only sets
output.texture_urlwhen the runner actually produces a texture — no fabricated PBR/textures. - GPU/weights are real probes.
/healthreportsgpu_availablefromtorch.cuda.is_available()andmodel_loadedfrom the weights dir existing — never hard-coded.
Build / run#
# context = repo root (the runner is copied from libs/)
docker build -f docker/runpod/trellis3d/Dockerfile -t oshun/trellis3d:latest .
docker run --gpus all -p 8080:8080 -v /path/to/TRELLIS.2-4B:/models/trellis2 oshun/trellis3d:latest
# then: OSHUN_TRELLIS_3D_URL=http://<host>:8080
Test#
The HTTP layer is contract-tested with no GPU (inference injected; the real
runner-CLI construction is verified with subprocess.Popen monkeypatched):
cd docker/runpod/trellis3d
pip install -r requirements.txt pytest httpx
pytest test_server.py -q