Open image-to-3D · GGUF · runs locally
One picture in,
a 3D model out.
TRELLIS.2-4B as a single GGUF file. Run it on your own GPU, send it an image over an OpenAI-style endpoint, and get back a textured mesh you can open in Blender or a game engine.
# 1. runtime
GGK_CUDA=1 pip install ggk
# 2. serve the model
ggk -m trellis2-4b-nvfp4.gguf \
--serve --port 8888
# 3. image in, mesh out
curl -f 127.0.0.1:8888/v1/images/edits \
-F image=@sheep.png -o sheep.glb
- Model
- TRELLIS.2-4B image encoder, flows and decoders in one file
- Download
- 5.65 GB nvfp4, one GGUF
- Hardware
- 6 GB GPU about 80 s per model at 512³
- Output
- glb · ply · obj mesh with per-vertex PBR
- API
- OpenAI-style POST /v1/images/edits
Try it
This page talks to your server, straight from the browser. Your pictures are sent nowhere else.
Endpoint: http://127.0.0.1:8888/v1/images/edits
ggk -m trellis2-4b-nvfp4.gguf --serve --port 8888
- One object per picture, whole and in view, on a plain backdrop or as a transparent cut-out.
- A picture with no plain backdrop to remove is modelled frame and all.
- Pipeline, format, seed and steps are under .
Your 3D model appears here.
Generation runs on your machine: about 80 seconds on a 6 GB GPU, several minutes for the high-resolution pipelines.
0:00
Generating…
Request
Quickstart
Two packages ship the same engine. Pick one; only the command name differs.
-
Install the runtime
Python 3.8+. The install compiles the engine: CPU by default, Metal on macOS. This model wants a GPU, so pick a backend.
GGK_CUDA=1 pip install ggk # NVIDIA GGK_HIP=1 pip install ggk # AMD ROCm GGK_VULKAN=1 pip install ggk # Vulkan pip install ggk # CPU only: works, but allow most of an hour per modelThe 3D server is in
ggk1.1.4 and newer, and ingguf-corereleases after 1.0.2. On Windows cmd, set the variable first:set GGK_CUDA=1, thenpip install ggk. -
Get the model file
One GGUF holds the whole pipeline. Download it from huggingface.co/gguf-org/trellis2-4b-gguf.
File What it is Size trellis2-4b-nvfp4.ggufTRELLIS.2-4B, NVFP4 weights. The one used on this page. 5.65 GB -
Start the server
--serveanswers over HTTP instead of writing one file and exiting.ggk -m trellis2-4b-nvfp4.gguf --serve --port 8888It listens on
127.0.0.1:8888at once. Add--api-key <key>to require a key,--host 0.0.0.0to serve your network,--mesh-pipeline 1024_cascadefor the full-resolution pipeline (wants about 11 GB, or patience). -
Turn a picture into a model
curl -f http://127.0.0.1:8888/v1/images/edits \ -F image=@sheep.png \ --output sheep.glbThe answer is the mesh file itself, when it is done: about 80 seconds on a 6 GB laptop GPU. Or skip the server and write one file:
ggk -m trellis2-4b-nvfp4.gguf --ref-image sheep.png -o sheep.glbKeep the
-f. Without it a failed request saves the JSON error message assheep.glb.
API
OpenAI has no 3D endpoint, so the server borrows the one with the same shape: the image edit. An image goes in, an asset comes out. OpenAI SDKs work with base_url set to your server.
POST /v1/images/edits
A multipart form with the picture as a file part, or a JSON body with the picture as base64. The response is the mesh file itself.
| Field | Meaning |
|---|---|
image required | The picture: PNG, JPEG, WebP or BMP. A file part in a form; base64 or a data: URI in JSON. URLs are not fetched. |
mask | The subject mask, white where the object is, the size of the image. Optional: an alpha channel does the same, and a plain backdrop is removed automatically. |
pipeline | 512, 1024, 1024_cascade, 1536_cascade or auto (default: by GPU memory). |
output_format | glb (default), ply or obj. |
response_format | Leave it out for the file. b64_json wraps it in OpenAI's images object: data[0].b64_json. |
seed | Default 42: the same picture returns the same mesh. -1 for a new take. |
steps, guidance | Sampling steps per stage (12) and guidance strength (7.5). |
background | auto (default) or keep: use the picture as it is, backdrop included. |
texture | false skips the material stages: the bare shape, in about two thirds of the time. |
model, prompt, size | Accepted and ignored. n must be 1. |
The mesh
.glb | Binary glTF 2.0, y-up, inside the unit cube. POSITION, NORMAL, COLOR_0 (base colour) and per-vertex metallic and roughness in _METALLIC_ROUGHNESS. |
.ply, .obj | z-up, with vertex colours. PLY also carries metallic and roughness per vertex. |
| Size | Dense: about 0.8 M vertices and 1.6 M triangles at 512³, 45 to 60 MB as GLB. Colour is per vertex, there are no UVs or texture maps. Decimate and bake in Blender before shipping it in a game. |
| Headers | X-Mesh-Vertices, X-Mesh-Triangles, X-Mesh-Resolution, X-Seed. |
Other endpoints
GET /health | {"status":"ok"} as soon as the port is open. |
GET /v1/models | The model, with meta.type = "image-to-3d", its pipelines and output formats. |
curl -f http://127.0.0.1:8888/v1/images/edits \
-F image=@sheep.png \
-F pipeline=512 \
-F seed=7 \
--output sheep.glb
# the bare shape as PLY, with an API key
curl -f http://127.0.0.1:8888/v1/images/edits \
-H "Authorization: Bearer $API_KEY" \
-F image=@sheep.png \
-F texture=false -F output_format=ply \
--output sheep.ply
# request.json: {"image": "<base64 of the file>", "seed": 7}
python -c "import base64, json; json.dump({'image': base64.b64encode(open('sheep.png','rb').read()).decode(), 'seed': 7}, open('request.json','w'))"
curl -f http://127.0.0.1:8888/v1/images/edits \
-H "Content-Type: application/json" \
-d @request.json \
--output sheep.glb
import base64, json, urllib.request
image = base64.b64encode(open("sheep.png", "rb").read()).decode()
req = urllib.request.Request(
"http://127.0.0.1:8888/v1/images/edits",
data=json.dumps({"image": image, "seed": 7}).encode(),
headers={"Content-Type": "application/json"},
)
# the answer comes when the mesh is done: allow minutes
with urllib.request.urlopen(req, timeout=1800) as res, open("sheep.glb", "wb") as f:
f.write(res.read())
import base64
from openai import OpenAI
client = OpenAI(base_url="http://127.0.0.1:8888/v1",
api_key="not-needed", timeout=1800)
result = client.images.edit(
model="trellis2",
image=open("sheep.png", "rb"),
prompt="",
response_format="b64_json",
)
with open("sheep.glb", "wb") as f:
f.write(base64.b64decode(result.data[0].b64_json))
Errors come back as JSON: {"error": {"code": 400, "message": "…"}}. One model is generated at a time; concurrent requests queue.
For AI agents
Hand your coding agent one file and it can install the runtime, start the server and turn pictures into models. It is plain text, self-contained, and needs no JavaScript to read.
/llms-full.txtThe complete guide: install, the model file, server options, every request field, output formats, timings, pitfalls./llms.txtThe short index, in the llms.txt convention.
Read llms-full.txt and follow it:
install ggk with the GPU backend for this machine, start the
TRELLIS.2 image-to-3D server on port 8888, then turn
sheep.png into a 3D model and save it as sheep.glb. Use
curl -f, and wait for the response: it can take minutes.