API de recherche de modèles 3D, téléchargements directs et authentification de plugins

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" \
  "/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"