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

Examples

curl -H "Authorization: Bearer $API_TOKEN" \
  "https://free3d.online/api/download/formats/PRODUCT_GUID"

curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  "https://free3d.online/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" \
  "https://free3d.online/api/plugin/download/direct" \
  -d '{"guid":"PRODUCT_GUID","format":"fbx","lod":"100k","variant":"static","relativePath":"uploads_files_6372157_100k/example.fbx"}'

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