3D model search API, topology-first direct downloads, and plugin auth

Public Search

Model discovery remains public. Use browse for listings, search for ranked results, and filters for UI controls.

Agent Auth

Use the user-token agent flow for AI agents and automation. Register or log in, store the token, then use it on account and download routes.

{
  "email": "agent@example.com",
  "password": "choose-a-strong-password",
  "name": "Agent Account"
}

Agent Direct Download

First discover exact files for a model, then call the direct route with the exact file descriptor. This matters because one model can expose the same extension across multiple topology folders.

{
  "guid": "product-guid",
  "format": "fbx",
  "lod": "100k",
  "relativePath": "uploads_files_6372157_100k/example.fbx"
}

{
  "ok": true,
  "guid": "product-guid",
  "format": "fbx",
  "lod": "100k",
  "downloadUrl": "https://worker-0001.free3d.online/data/.../example.fbx",
  "fileName": "example.fbx",
  "contentType": "application/octet-stream",
  "relativePath": "uploads_files_6372157_100k/example.fbx",
  "chargedUsd": 1,
  "balanceRemainingUsd": 99
}

• Use the `formats` response as the source of truth for the exact `relativePath` you must pass back.
• If the same extension exists in `1k`, `10k`, and `100k`, the tuple `format + lod + relativePath` removes ambiguity.
• Pricing is per model unlock, not per subsequent file after the model is already unlocked.

Plugin Auth

Plugins stay on the browser-approved auth flow. Search is public, but account-aware downloads require a plugin token.

{
  "appSlug": "free3d-3dsmax",
  "appName": "Free3D 3ds Max Plugin",
  "appVersion": "0.1.0",
  "pluginFamily": "3dsmax",
  "deviceName": "artist-workstation",
  "requestedScopes": ["account:read", "balance:read", "entitlements:read", "download:direct", "scene:import"]
}

Plugin Direct Download

The plugin reads `fbxVariants` and `maxVariants` from the formats route, then calls the direct route for the exact scene file and support files. Plugins should treat the formats response as authoritative and never guess paths.

{
  "guid": "product-guid",
  "format": "fbx",
  "lod": "100k",
  "variant": "static",
  "relativePath": "uploads_files_6372157_100k/example.fbx"
}

{
  "ok": true,
  "downloadUrl": "https://worker-0001.free3d.online/data/.../example.fbx",
  "supportFilesCount": 4,
  "supportFiles": [
    {
      "relativePath": "uploads_files_6372157_100k/textures/example_basecolor.png",
      "url": "https://worker-0001.free3d.online/data/.../example_basecolor.png"
    }
  ],
  "import": {
    "dcc": "3dsmax",
    "mode": "import",
    "target": "current_scene",
    "sceneFileUrl": "https://worker-0001.free3d.online/data/.../example.fbx",
    "sceneRelativePath": "uploads_files_6372157_100k/example.fbx",
    "assetsRootUrl": "https://worker-0001.free3d.online/data/.../uploads_files_6372157_100k",
    "searchPaths": ["uploads_files_6372157_100k", "uploads_files_6372157_100k/textures"]
  }
}

• For characters, `variant` can distinguish the animated FBX from the static FBX in the same topology.
• Prefer the exact `downloadRequest.body` emitted by the formats response instead of rebuilding request bodies in the plugin.

Browser Download Routes

The model page follows the same topology-first contract. Signed-in browser users first choose topology, then format, and the UI resolves either an exact direct file or a short-lived generated archive.

• `/download/{guid}/format/{ext}` redirects to the final worker `directUrl` for the selected file.
• `/download/{guid}/textures` builds a no-compression ZIP with the selected topology's PBR textures, caches it for 1 hour, then removes it.
• `/download/{guid}/all` builds a no-compression ZIP with all files from the selected topology folder, caches it for 1 hour, then removes it.
• These browser routes still use the same exact selection tuple: `ext` + `lod` + `relativePath`.

Worker Sync

Main-site sync stays transactional and async-indexed, and the worker contract uses direct static files, rendered posters, and `files[]` inventory as the single download source of truth.

• `prepare` is forbidden in the public contract.
• Every meaningful file or poster change must bump product `version`.
• `previewSmallUrl`, `previewMediumUrl`, and `previewLargeUrl` must be rendered posters, not texture JPGs.
• Topology detection must remain stable for `1k`, `10k`, and `100k` folders because the main-site UI groups formats by topology.

3ds Max Starter

The public 3ds Max starter uses the same browser-approved plugin auth flow and resolves downloads through the topology-first direct-file contract, using exact `fbxVariants` metadata returned by the API.

Unity Starter

The public Unity starter is a single-file editor script. It uses the same browser-approved plugin auth flow, the same public search APIs, and the same direct-file plugin download contract, while checking the published update feed on editor startup.

YAML Contracts

MCP Server (Model Context Protocol)

AI-native interface for Claude, Cursor, Windsurf, and other MCP-compatible agents. Search and download 3D models through structured tools without writing HTTP client code.

Quick Start

LowPoly models (LOD 1k, ~1k–5k polygons) are free and require no API key. HighQuality versions (10k/100k/source) require an API key from your account.

Available Tools

• search_models — Search by keywords, category, format, or polygon count
• get_model_details — Full metadata, available LODs, preview URLs
• download_model — Time-limited download URL (15 min TTL)
• list_categories — Browse all model categories with counts

Claude Desktop Config

{
  "mcpServers": {
    "free3d": {
      "command": "python",
      "args": ["/path/to/free3d_mcp_server.py", "--transport", "stdio"]
    }
  }
}

Example: Search LowPoly Models

// Tool: search_models
{
  "query_string": "robot",
  "category_string": "characters",
  "limit_int": 10
}

// Response includes license_type_string:
// "lowpoly_free" = free to download
// "premium" = requires API key for HQ versions

Example: Download (LowPoly Free)

// Tool: download_model
{
  "model_id_string": "mdl_07fcd353-3dc7-4303-932d-0af202bab7c8",
  "format_string": "glb",
  "lod_string": "1k"
}

// Response: direct_download_url_string with 15-min token

Example: Download HighQuality (Requires API Key)

// Tool: download_model
{
  "model_id_string": "mdl_07fcd353-3dc7-4303-932d-0af202bab7c8",
  "format_string": "glb",
  "lod_string": "100k",
  "api_key_string": "fr3d_live_xxxxxxxx"
}

// Without key: HTTP 402 Payment Required
// With valid key: direct download URL

Self-Host (Docker)

git clone https://github.com/free3d/mcp-server.git
cd mcp-server
docker-compose up -d

Resources

Rate limits: 100 req/min for LowPoly search, 60 req/min for HighQuality downloads. No authentication required for LowPoly (1k) models.

Examples

curl -H "Authorization: Bearer $API_TOKEN" \
  "/api/download/formats/PRODUCT_GUID"

curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  "/api/download/direct" \
  -d '{"guid":"PRODUCT_GUID","format":"fbx","lod":"100k","relativePath":"uploads_files_6372157_100k/example.fbx"}'

curl -X POST \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  "/api/plugin/download/direct" \
  -d '{"guid":"PRODUCT_GUID","format":"fbx","lod":"100k","variant":"static","relativePath":"uploads_files_6372157_100k/example.fbx"}'

curl -I \
  "/download/PRODUCT_GUID/format/fbx?lod=100k&relativePath=uploads_files_6372157_100k/example.fbx"