Version: 1.0.0 |
Default port: 7960 |
Launch: python api_spz/main_api.py --host 127.0.0.1 --port 7960
Wraps Microsoft TRELLIS.2-4B for use with StableProjectorz. Trellis 2 always generates shape + PBR texture in a single pass. Output is GLB with baked base color, metallic, and roughness maps.
GET /status is optional and only useful for monitoring progress from a separate connection during a long generation.GET /download/spz-ui-layout/generation-3d-panel to build the UI panelPOST /generate with JSON body containing all parameters + base64 imagesmodel_urlGET /download/modelPOST /generate_no_preview (single image) or POST /generate_multi_no_preview (multi-image) with form data"model_url": "/download/model"GET /download/model to retrieve the GLB503.Health check. Returns server status and whether a generation is in progress.
{
"status": "running",
"message": "Trellis2 API is operational",
"busy": false
}Returns the status of the current or most recent generation. Useful for progress monitoring from a separate connection while a generation endpoint is blocking.
{
"status": "PROCESSING" | "COMPLETE" | "FAILED",
"progress": 0-100,
"message": "Generating 3D mesh and texture...",
"busy": true
}Primary endpoint used by StableProjectorz. Accepts a JSON body with all parameters and base64-encoded images. Blocks until generation completes.
{
"seed": 1234,
"guidance_scale": 7.5,
"num_inference_steps": 12,
"resolution": 1,
"mesh_simplify": 50,
"apply_texture": true,
"single_multi_img_input": ["data:image/png;base64,iVBOR..."]
}0 = 512, 1 = 1024, 2 = 1536. Maps to pipeline types 512, 1024_cascade, 1536_cascade.
50 = 50,000 faces.
{
"status": "COMPLETE",
"progress": 100,
"message": "Generation complete",
"model_url": "/download/model"
}Direct generation from a single image via multipart form data. Blocks until generation completes.
file or image_base64./generate.
Accepts multiple images via multipart form data. Trellis 2 uses only the first image. Blocks until generation completes.
/generate_no_preview./generate.
Cancel the current generation. The cancellation is injected between sampling steps and typically takes effect within 1–2 seconds.
The blocked generation endpoint will return 499.
{"status": "interrupt_requested"}
// or if nothing is running:
{"status": "no_generation_in_progress"}Download the generated GLB file. Available after generation completes successfully. Returns 404 if no model exists.
model/gltf-binary), with PBR textures stored as PNG.
Returns the StableProjectorz UI layout definition as plain text. SPZ uses this to dynamically build the generation panel with sliders, dropdowns, and toggles.
text/plain; charset=utf-8).
Returns the list of supported operation types. Trellis 2 always generates mesh with texture in a single pass.
["make_meshes_and_tex"]Trellis 2 runs three sampling stages internally. The SPZ UI exposes guidance_scale (controls sparse structure guidance) and num_inference_steps (applied to all stages).
All other sampler parameters are hardcoded to match the official Gradio app defaults:
| Stage | guidance_strength | guidance_rescale | steps | rescale_t |
|---|---|---|---|---|
| 1. Sparse Structure | user slider (def 7.5) | 0.7 | user slider (def 12) | 5.0 |
| 2. Shape | 7.5 | 0.5 | user slider (def 12) | 3.0 |
| 3. Texture | 1.0 | 0.0 | user slider (def 12) | 3.0 |
512 |
1024 → 1024_cascade |
1536 → 1536_cascade
remesh_band=1, remesh_project=0).
Mesh simplified to nvdiffrast limit (16M triangles) before export, then decimated to user-specified face count.
PBR texture baked from the voxel attribute volume via trilinear sampling. Textures stored as PNG inside the GLB.
| Code | Meaning |
|---|---|
| 400 | Invalid parameters or missing image |
| 404 | Model file not found (no generation completed yet) |
| 499 | Generation cancelled by user via /interrupt |
| 500 | Internal server error during generation |
| 503 | Server busy — another generation is already running |