Zlim Docs

Zlim optimizes 3D models to GLB. Integrate three ways: the local CLI and MCP server run the engine in-process with no account or API key, and the hosted REST API runs async jobs at scale.

Quickstart

The fastest path is the local CLI. It runs the optimization engine in-process — no account, no API key, no upload:

zlim optimize model.fbx -o model.glb -p balanced
# writes model.glb and prints a JSON report
# (input vs. output: faces, vertices, bytes)

Working inside an AI agent? The MCP server exposes the same local engine as tool calls. Need a hosted, async pipeline at scale? Use the REST API: create a job, upload the file, poll until it succeeds, then download the optimized GLB.

REST API reference

The hosted API is asynchronous and grant-based: you create a job, upload the raw file bytes to a signed URL, mark the upload complete, poll until the job reaches a terminal status, then fetch a signed download URL. All requests authenticate with a Bearer API key.

1. Create a job

POST /api/v1/jobs with a JSON body. Returns 201 with the job and an uploadGrant containing a putUrl.

curl -X POST https://zlim.ai/api/v1/jobs \
  -H "Authorization: Bearer $ZLIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskType": "model.optimize",
    "filename": "model.fbx",
    "options": { "preset": "balanced" }
  }'

# Response (201):
{
  "job": {
    "id": "1f3c…",
    "status": "waiting_upload",
    "taskType": "model.optimize"
  },
  "uploadGrant": {
    "putUrl": "https://…"
  }
}

2. Upload the file, then complete the upload

PUT the raw file bytes to uploadGrant.putUrl, then POST .../complete-upload to move the job from waiting_upload to queued.

# Upload the raw bytes to the signed putUrl
curl -X PUT "$PUT_URL" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @model.fbx

# Mark the upload complete → job becomes "queued"
curl -X POST https://zlim.ai/api/v1/jobs/$JOB_ID/complete-upload \
  -H "Authorization: Bearer $ZLIM_API_KEY"

3. Poll status, then download

Poll GET /api/v1/jobs/:id until a terminal status (succeeded, failed, or cancelled). When succeeded, fetch a signed download URL from GET /api/v1/jobs/:id/result-url.

# Poll until terminal
curl https://zlim.ai/api/v1/jobs/$JOB_ID \
  -H "Authorization: Bearer $ZLIM_API_KEY"
# { "job": { "id": "1f3c…", "status": "succeeded", … } }

# Get a signed download URL (only when status is "succeeded")
curl https://zlim.ai/api/v1/jobs/$JOB_ID/result-url \
  -H "Authorization: Bearer $ZLIM_API_KEY"
# { "url": "https://…", "expiresAt": "…" }

# Download the optimized GLB
curl -o model.glb "$RESULT_URL"

Endpoints

CLI

Commands

Four commands. All read a local model and write a GLB (or a JSON report).

optimize

Runs the optimization pipeline for the chosen preset and prints a JSON report of input vs. output metrics.

zlim optimize model.fbx -o model.glb -p balanced
# prints a JSON report:
{
  "input":  { "format": "fbx", "faces": 1240000, "vertices": 642000, "bytes": 18400000 },
  "output": { "faces": 286000, "vertices": 150000, "bytes": 3960000,
              "drawCalls": 12, "materials": 4, "textures": 3 },
  "stages": [ { "name": "repair-input", "ms": 12 } ],
  "warnings": []
}

convert

Converts any supported format to GLB with geometry repair only — no lossy optimization. Use optimize when you want size reduction.

zlim convert assembly.step -o part.glb
# Converted assembly.step -> part.glb (3960000 bytes, step -> glb)

analyze

Inspects a model and prints its input metrics without producing output. Add --json for machine-readable output.

zlim analyze model.fbx
# Format:   fbx
# Faces:    1240000
# Vertices: 642000
# Bytes:    18400000

batch

Pass files or glob patterns. Each input becomes its own optimized GLB in the output directory, with per-file failure isolation; the command exits non-zero if any file fails.

zlim batch "assets/**/*.fbx" "assets/**/*.obj" -o dist/ -p balanced --concurrency 4
# STATUS  INPUT             BYTES                REDUCTION  FACES               NOTE
# ok      assets/chair.fbx  18400000 -> 3960000  78.5%      1240000 -> 286000
# ok      assets/table.obj  9200000 -> 2300000   75%        420000 -> 110000
#
# 2 ok, 0 failed (2 total)

CLI flags

MCP server

Zlim ships an MCP (Model Context Protocol) server (@zlim/mcp) so AI agents — Claude, Cursor, or any MCP-compatible host — can optimize, convert, and analyze 3D models as tool calls.

Tools exposed

Connect to Claude Desktop (local)

Add the following to your claude_desktop_config.json. No env vars are needed for local mode:

{
  "mcpServers": {
    "zlim": {
      "command": "npx",
      "args": ["-y", "@zlim/mcp"]
    }
  }
}

Cloud mode (optional)

To delegate work to the hosted API instead of running locally, set both env vars. This also enables the zlim_job_status and zlim_job_result tools:

{
  "mcpServers": {
    "zlim": {
      "command": "npx",
      "args": ["-y", "@zlim/mcp"],
      "env": {
        "ZLIM_API_URL": "https://zlim.ai",
        "ZLIM_API_KEY": "your_api_key_here"
      }
    }
  }
}

Authentication

The local CLI and MCP server need no authentication. The hosted REST API authenticates each request with a bearer API key in the Authorization header (an x-api-key header or a signed-in dashboard session also work):

Authorization: Bearer <your_api_key>

Keys are managed from the Keys dashboard. Create multiple keys to scope access per environment (dev, staging, production).

Jobs reference

Job statuses

Terminal statuses are succeeded, failed, and cancelled. Poll GET /api/v1/jobs/:id until one of these is reached.

Supported formats

Every supported format outputs to GLB. More formats are on the roadmap — marked coming soon below.