Optimize a 3D model

Send a textured GLB and a triangle count between 1,000 and 200,000. The model is rebuilt at that count and gets new base-colour, metal/roughness and normal maps, tuned until it renders like the original from every side. Where simplification has to keep the original textures and stops at a quarter of the triangles or so, this goes all the way down. The result keeps the input's coordinates and scale. Start the job, keep its id and poll: it takes a few minutes.

Formats

.glb (self-contained, uncompressed, one material)

Outputs

model.glb (three 2048² or 1024² textures) and generation.json

Targets

1,000 to 200,000 triangles; inputs up to 2,000,000

Duration

Asynchronous; one-hour deadline including queueing and execution

Send the file as the request body with the options in the query string, or refer to it in a JSON body (upload_id or url) with an options object. The response is the new job; poll it until its status is final, then download the files in result.files.

# Idempotency-Key is required: repeating it returns the same job
curl "https://api.mcpbytes.com/v1/tools/optimize_3d_model/jobs?filename=model.glb&target_faces=15000&seed=42" \
  -H "Authorization: Bearer $MCPBYTES_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  -H "Idempotency-Key: optimize-example-001" \
  --data-binary @model.glb

{
  "tool": "optimize_3d_model",
  "status": "queued",
  "input_kind": "file",
  "workflow": {
    "stage": "Optimizing",
    "deadline": "2026-09-22T22:23:09.206Z",
    "cancel_pending": false,
    "refund_pending": false
  },
  "capabilities": {
    "can_cancel": true
  },
  "options": {
    "target_faces": 15000,
    "texture_resolution": 2048,
    "seed": 42
  },
  "result": null
}

# JOB_ID is the id from the create response; poll until status is final
curl "https://api.mcpbytes.com/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $MCPBYTES_API_KEY"

# Once status is succeeded, download the model from result.files[].url
curl -fsSLo model.glb "$MODEL_URL"

{
  "tool": "optimize_3d_model",
  "status": "succeeded",
  "result": {
    "files": [
      {
        "name": "model.glb",
        "bytes": 4143860,
        "content_type": "model/gltf-binary",
        "url": "https://api.mcpbytes.com/blob/dl/…"
      },
      {
        "name": "generation.json",
        "bytes": 2218,
        "content_type": "application/json",
        "url": "https://api.mcpbytes.com/blob/dl/…"
      }
    ],
    "notes": []
  },
  "compute_ms": 278600,
  "credits_charged": 60
}

Jobs of this tool take minutes. While one runs, workflow.stage says what is happening and workflow.deadline when it must finish. Cancel it with POST /v1/jobs/{id}/cancel while capabilities.can_cancel is true.

More on statuses, downloads and retention in Jobs & files.

One file per job, in one of these ways. The formats it accepts are listed in the overview.

# 1. Create an upload URL (valid for one hour)
curl https://api.mcpbytes.com/v1/uploads \
  -H "Authorization: Bearer $MCPBYTES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "model.glb"}'

# 2. PUT the file to the "url" from the response
curl -X PUT --data-binary @model.glb "$UPLOAD_URL"

# 3. Start the job with the "upload_id"
curl https://api.mcpbytes.com/v1/tools/optimize_3d_model/jobs \
  -H "Authorization: Bearer $MCPBYTES_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"upload_id\": \"$UPLOAD_ID\",
    \"options\": {
      \"target_faces\": 15000
    },
    \"idempotency_key\": \"optimize_3d_model-upload-001\"
  }"

Put options in the query string when the file is the request body, in the options object of a JSON body, or pass them as arguments of the MCP tool. Leave an option out to use its default.

A succeeded job lists its files in result.files, each with a download url.

Download links last up to 24 hours, capped by output retention; read the job again for fresh links. Fine print and details thinner than a texel can soften in the new textures.

• target_faces is a reduction request: an input already at or below it keeps its geometry and gets new textures. Read the achieved count in generation.json.
• Pass model.glb of a create_3d_model or create_3d_model_from_image job as job_file, with no download in between.
• Fine print and details thinner than a texel can soften in the new textures.
• Export one static, textured mesh. Skinned, animated or morph-target models, several materials and vertex colours without a texture are refused.
• A job takes a few minutes: keep its id and poll. Repeating the request with the same idempotency key returns the same job instead of a new charge.

Your agent calls optimize_3d_model. Connect it to https://api.mcpbytes.com/mcp/3d for this tool and the rest of its family (Create a 3D model, Create a 3D model from an image, Simplify a 3D model, Split a 3D model into parts, Inspect a 3D model), or to https://api.mcpbytes.com/mcp for every tool.

claude mcp add --transport http mcpbytes \
  https://api.mcpbytes.com/mcp/3d

codex mcp add mcpbytes --url https://api.mcpbytes.com/mcp/3d \
  --bearer-token-env-var MCPBYTES_API_KEY

{
  "mcpServers": {
    "mcpbytes": {
      "url": "https://api.mcpbytes.com/mcp/3d",
      "headers": {
        "Authorization": "Bearer ${env:MCPBYTES_API_KEY}"
      }
    }
  }
}

Arguments

The tool's options are flat arguments. Besides them:

What the agent sees

Setup for every client, and how agents upload files and read results: Connect over MCP.

The MCPBytes skill teaches agents this tool, in references/optimize_3d_model.md. Agents without MCP run it through the REST API with the skill's script, which reads your key from MCPBYTES_API_KEY:

python scripts/mcpbytes.py run optimize_3d_model model.glb \
  -o target_faces=15000 --out optimized/
# Or an earlier job's output, without downloading it
python scripts/mcpbytes.py run optimize_3d_model \
  --job-file j_... model.glb -o target_faces=15000 --no-wait
python scripts/mcpbytes.py job j_...

60 credits per job. The price is charged before paid processing starts, and a canceled job is refunded. A job that fails costs nothing: its charge is refunded.

One credit balance pays for every tool, and a new account starts with free credits. See Credits & prices or buy credits.

GET /v1/me returns your limits and current usage; Limits & errors explains what happens when one is reached.

A failed job comes back with error.code, error.message and often error.hint. Codes are stable. Inputs that fail with a validation error will fail again unchanged.

Requests can also fail before a job starts, with an HTTP status: see HTTP errors.

• Create a 3D modelIts model.glb goes straight in as job_file.create_3d_model
• Create a 3D model from an imageIts model.glb goes straight in as job_file.create_3d_model_from_image
• Simplify a 3D modelKeeps the original textures and runs in seconds, but stops around 15 to 25 % of the triangles on atlas-textured models.simplify_3d_model