image-to-3dgame asset
checking

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.

quickstart
# 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

    • 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.

    Quickstart

    Two packages ship the same engine. Pick one; only the command name differs.

    1. 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 model

      The 3D server is in ggk 1.1.4 and newer, and in gguf-core releases after 1.0.2. On Windows cmd, set the variable first: set GGK_CUDA=1, then pip install ggk.

    2. Get the model file

      One GGUF holds the whole pipeline. Download it from huggingface.co/gguf-org/trellis2-4b-gguf.

      FileWhat it isSize
      trellis2-4b-nvfp4.ggufTRELLIS.2-4B, NVFP4 weights. The one used on this page.5.65 GB
    3. Start the server

      --serve answers over HTTP instead of writing one file and exiting.

      ggk -m trellis2-4b-nvfp4.gguf --serve --port 8888

      It listens on 127.0.0.1:8888 at once. Add --api-key <key> to require a key, --host 0.0.0.0 to serve your network, --mesh-pipeline 1024_cascade for the full-resolution pipeline (wants about 11 GB, or patience).

    4. Turn a picture into a model

      curl -f http://127.0.0.1:8888/v1/images/edits \
        -F image=@sheep.png \
        --output sheep.glb

      The 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.glb

      Keep the -f. Without it a failed request saves the JSON error message as sheep.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.

    FieldMeaning
    image requiredThe picture: PNG, JPEG, WebP or BMP. A file part in a form; base64 or a data: URI in JSON. URLs are not fetched.
    maskThe 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.
    pipeline512, 1024, 1024_cascade, 1536_cascade or auto (default: by GPU memory).
    output_formatglb (default), ply or obj.
    response_formatLeave it out for the file. b64_json wraps it in OpenAI's images object: data[0].b64_json.
    seedDefault 42: the same picture returns the same mesh. -1 for a new take.
    steps, guidanceSampling steps per stage (12) and guidance strength (7.5).
    backgroundauto (default) or keep: use the picture as it is, backdrop included.
    texturefalse skips the material stages: the bare shape, in about two thirds of the time.
    model, prompt, sizeAccepted and ignored. n must be 1.

    The mesh

    .glbBinary 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, .objz-up, with vertex colours. PLY also carries metallic and roughness per vertex.
    SizeDense: 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.
    HeadersX-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/modelsThe 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

    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.
    Open as text
    Prompt to paste into your agent
    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.

    Settings

    Where the playground sends pictures, and how models are generated. Saved in this browser only.

    The image-to-3D URL of your server, or of a gateway in front of it.

    Generation · empty = the server's default · 512 fits a 6 GB GPU, the cascades are the full quality