API SVILUPPATORI 3DLIGO & INTEGRAZIONE IA

Automatizza il tuo negozio 3D con il codice o Assistenti IA

Usa l'API REST di 3DLigo per caricare modelli 3D (.stl, .3mf, .obj, .step), aggiornare i prodotti, pubblicare nuove versioni o collegare strumenti IA come Cursor, Claude e ChatGPT.

URL di Base (Base URL)REST JSON / Multipart
https://3dligo.com/api/v1/developer
Autenticazione
Bearer Token / X-API-Key
Permesso Predefinito
Read (Lettura)
Caricamento & Modifica
Write (Scrittura - Opzionale)
Formati Supportati
STL, 3MF, OBJ, STEP, ZIP + Media

Come funziona in 3 passaggi

Collega il tuo negozio ai tuoi script o al tuo assistente IA in pochi minuti.

01

1. Genera la tua Chiave API

Vai su store.3dligo.com/settings nella scheda "API & Developers". "Read" è selezionato di default; spunta anche "Write" per caricare modelli e aggiornare i prodotti.

02

2. Invia la chiave nell'Header HTTP

Includi la chiave nelle richieste HTTP tramite "Authorization: Bearer TUA_API_KEY" o "X-API-Key: TUA_API_KEY".

03

3. Carica modelli e gestisci i prodotti

Carica i file tramite /files/upload e usa i percorsi restituiti su /products per creare o aggiornare i prodotti.

Autenticazione

Autentica ogni richiesta inviando la chiave API negli header HTTP:

Opzione 1 — Authorization Bearer (Consigliato)
Authorization: Bearer ligo_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Opzione 2 — Header X-API-Key
X-API-Key: ligo_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
⚠ Regola importante: Non inviare la chiave nell'URLLe chiavi passate nell'URL (?api_key=...) vengono rifiutate con 400 Bad Request.

Permessi (Scopes) e Limiti di Richiesta

Scegli i permessi necessari durante la creazione della chiave:

PermessoPredefinitoLimiteOperazioni Consentite
readSì (Default)120 / minElenca profilo negozio, prodotti, dettagli, categorie e collezioni
writeOpzionale30 / minCrea, aggiorna, aggiungi versioni ed elimina prodotti
uploadIncluso con Write15 / minCarica modelli 3D e immagini/video (fino a 500 MB)

Esempi di codice nei linguaggi più diffusi

Scegli il tuo linguaggio di programmazione e copia il codice pronto all'uso.

Python — Automate 3D model uploads and product management with Python (requests) or inside Blender Python scripts:
import os
import requests

BASE_URL = "https://3dligo.com/api/v1/developer"
API_KEY = os.environ.get("LIGO_API_KEY", "ligo_live_YOUR_API_KEY")

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Accept": "application/json",
}

# 1. Mağaza Ürünlerini Listele (GET /products)
products_res = requests.get(f"{BASE_URL}/products", headers=headers, params={"limit": 20})
print("Store Products:", products_res.json())

# 2. 3D Model Dosyasını Yükle (POST /files/upload)
with open("crystal_dragon_v2.3mf", "rb") as f:
    model_res = requests.post(
        f"{BASE_URL}/files/upload",
        headers=headers,
        data={"category": "models"},
        files={"file": ("crystal_dragon_v2.3mf", f, "application/octet-stream")},
    )
model_data = model_res.json()["data"]

# 3. Kapak Görselini Yükle (POST /files/upload)
with open("cover_render.webp", "rb") as f:
    img_res = requests.post(
        f"{BASE_URL}/files/upload",
        headers=headers,
        data={"category": "images"},
        files={"file": ("cover_render.webp", f, "image/webp")},
    )
img_data = img_res.json()["data"]

# 4. Yeni Ürünü Yayınla (POST /products)
payload = {
    "title": "Articulated Crystal Dragon v2",
    "description": "<p>High-detail print-in-place crystal dragon.</p>",
    "price": 149.90,
    "discount_price": 99.90,
    "category_id": 1,
    "sku": "CFD-DRG-002",
    "status": "published",
    "tags": ["dragon", "articulated", "stl", "3mf"],
    "files": [
        {
            "file_url": model_data["path"],
            "file_type": "model",
            "display_name": model_data["original_name"],
            "file_size_kb": model_data["size_kb"],
            "is_primary": True,
        },
        {
            "file_url": img_data["url"],
            "file_type": "image",
            "display_name": img_data["original_name"],
            "file_size_kb": img_data["size_kb"],
            "is_primary": True,
        },
    ],
}

create_res = requests.post(f"{BASE_URL}/products", headers=headers, json=payload)
print("Created Product:", create_res.json())
✨ AUTOMAZIONE IA

Collega gli strumenti IA (ChatGPT, Claude, Cursor, Copilot)

Copia il prompt di sistema qui sotto in Cursor, Claude o ChatGPT per gestire il tuo negozio in linguaggio naturale.

🤖 Cursor AI🤖 Claude / Claude Code🤖 ChatGPT (GPT-4o / o3)🤖 GitHub Copilot🤖 Windsurf🤖 n8n / Make AI Agent

Come usare l'API con l'IA

STEP 1Crea una chiave API con permessi "Read" e "Write" nelle impostazioni del negozio.
STEP 2Copia il Prompt di Sistema IA qui sotto e incollalo nel tuo assistente IA.
STEP 3Chiedi all'IA cosa fare con semplici istruzioni testuali.
Prompt di Sistema IA copiabile (Cursor / Claude / ChatGPT)
You are connected to my 3DLigo 3D Model Store via the official 3DLigo Developer REST API.

### API Configuration
- Base URL: https://3dligo.com/api/v1/developer
- Authentication Header: Authorization: Bearer <MY_3DLIGO_API_KEY> (or X-API-Key: <MY_3DLIGO_API_KEY>)
- Never send the API key in URL query parameters.

### Available Endpoints
1. GET /store -> Returns store info and storage quota.
2. GET /categories -> Returns marketplace category IDs and slugs.
3. GET /collections -> Returns my store's collection IDs.
4. GET /meta-tags -> Returns printer, filament, and part tags.
5. GET /products?page=1&limit=20&status=published&q=keyword -> Lists my store's products.
6. GET /products/:id -> Returns full details, files, and versions of product :id.
7. POST /files/upload (multipart/form-data)
   - Form fields: "category" ("models" for .stl/.3mf/.obj/.step/.zip or "images" for .webp/.png/.jpg) and "file" (binary file).
   - Returns: { "data": { "path": "...", "url": "...", "original_name": "...", "size_kb": 1234 } }
8. POST /products (application/json)
   - Body: {
       "title": "String (required)",
       "description": "HTML or text description",
       "price": 149.90,
       "discount_price": 99.90,
       "category_id": 1,
       "sku": "OPTIONAL-SKU",
       "status": "published", // or "draft"
       "license_type": "personal", // or "commercial"
       "tags": ["tag1", "tag2"],
       "files": [
         { "file_url": "<path from /files/upload>", "file_type": "model", "display_name": "model.3mf", "file_size_kb": 1234, "is_primary": true },
         { "file_url": "<url from /files/upload>", "file_type": "image", "display_name": "cover.webp", "file_size_kb": 200, "is_primary": true }
       ]
     }
9. PUT /products/:id (application/json) -> Updates title, description, price, discount_price, status, category_id, tags, or files.
10. POST /products/:id/versions (application/json) -> Publishes a new version: { "version_number": "2.0.0", "changelog": "Release notes", "files": [...] }
11. DELETE /products/:id -> Deletes or archives product :id.

My 3DLigo API Key is: ligo_live_PASTE_YOUR_KEY_HERE
Please help me automate my store tasks using these endpoints.

Esempi di comandi da dare all'IA

Caricamento multiplo di modelli 3D

"Carica tutti i file .3mf e .stl dalla cartella ./Models insieme alle immagini di copertina sul mio negozio 3DLigo al prezzo di 14,99 €."

Aggiornamento sconti in blocco

"Elenca tutti i prodotti del mio negozio 3DLigo e applica uno sconto del 20% a quelli sopra i 10 €."

Pubblica una nuova versione

"Trova il prodotto 'Crystal Dragon', carica dragon_v2_fixed.3mf e aggiungilo come versione 2.0.0."

Riferimento Endpoint API

Tutti gli endpoint operano esclusivamente sul negozio associato alla tua chiave API.

GET/api/v1/developer/store
Scope: read120 req/min

Get Store Profile & Storage Quota

Returns the authenticated store profile, approval status, total product count, and storage quota usage.

Esempio Risposta (JSON)
{
  "success": true,
  "data": {
    "store_id": 42,
    "name": "CyberForge 3D Studio",
    "slug": "cyberforge-3d-studio",
    "description": "High-detail sci-fi miniatures and terrain",
    "status": "approved",
    "is_verified": true,
    "product_count": 128,
    "storage": {
      "used_kb": 1458200,
      "quota_kb": 52428800,
      "used_percent": 2.78
    },
    "api_key": {
      "scopes": ["read", "write"]
    }
  }
}
GET/api/v1/developer/categories
Scope: read120 req/min

List Categories

Returns all active 3DLigo marketplace categories (IDs, names, and slugs) for use when creating or updating products.

Esempio Risposta (JSON)
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Miniatures & Tabletop",
      "slug": "miniatures-tabletop",
      "parent_id": null
    },
    {
      "id": 5,
      "name": "Cosplay & Props",
      "slug": "cosplay-props",
      "parent_id": null
    }
  ]
}
GET/api/v1/developer/collections
Scope: read120 req/min

List Store Collections

Lists custom collections belonging to your store. Pass these IDs in collection_ids when creating or updating products.

Esempio Risposta (JSON)
{
  "success": true,
  "data": [
    {
      "id": 12,
      "title": "2026 Mech Series",
      "slug": "2026-mech-series"
    }
  ]
}
GET/api/v1/developer/meta-tags
Scope: read120 req/min

List Printer, Filament & Part Meta Tags

Returns global printer models, filament materials (PLA, PETG, ABS, Resin, etc.), and part tags.

Esempio Risposta (JSON)
{
  "success": true,
  "data": {
    "printers": [{ "id": 1, "name": "Bambu Lab X1C", "slug": "bambu-lab-x1c" }],
    "filaments": [{ "id": 10, "name": "PLA+", "slug": "pla-plus" }],
    "parts": [{ "id": 22, "name": "No Supports Required", "slug": "no-supports" }]
  }
}
GET/api/v1/developer/products
Scope: read120 req/min

List Store Products

Lists products belonging to your store with pagination, status filter, and search query.

Parametri
pageinteger
Page number (default: 1)
limitinteger
Items per page (default: 20, max: 100)
statusstring
Filter by status: published, draft, pending, archived
qstring
Search query matching title or SKU
Esempio Risposta (JSON)
{
  "success": true,
  "data": {
    "items": [
      {
        "id": 1042,
        "title": "Articulated Crystal Dragon v2",
        "slug": "articulated-crystal-dragon-v2",
        "sku": "CFD-DRG-002",
        "price": 149.9,
        "discount_price": 99.9,
        "status": "published",
        "thumbnail": "https://cdn.3dligo.com/public/stores/42/images/cover.webp",
        "downloads": 384,
        "views": 4910,
        "category_id": 1,
        "license_fee": 0,
        "created_at": "2026-11-10T14:22:00Z",
        "updated_at": "2026-11-14T19:05:11Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "total_pages": 1
    }
  }
}
GET/api/v1/developer/products/:id
Scope: read120 req/min

Get Product Details, Files & Versions

Retrieves full details of a single store product including uploaded 3D model files, gallery images, tags, and version history.

Esempio Risposta (JSON)
{
  "success": true,
  "data": {
    "id": 1042,
    "title": "Articulated Crystal Dragon v2",
    "slug": "articulated-crystal-dragon-v2",
    "description": "<p>Print-in-place articulated dragon. No supports needed.</p>",
    "sku": "CFD-DRG-002",
    "price": 149.9,
    "discount_price": 99.9,
    "status": "published",
    "category_id": 1,
    "tags": ["dragon", "articulated", "print-in-place"],
    "files": [
      {
        "id": 8801,
        "file_type": "model",
        "display_name": "crystal_dragon_v2.3mf",
        "file_size_kb": 18420,
        "is_primary": true
      },
      {
        "id": 8802,
        "file_type": "image",
        "display_name": "cover_render.webp",
        "file_url": "https://cdn.3dligo.com/public/stores/42/images/cover_render.webp",
        "is_primary": true
      }
    ],
    "versions": [
      {
        "id": 310,
        "version_number": "1.0.0",
        "changelog": "Initial release",
        "created_at": "2026-11-10T14:22:00Z"
      }
    ]
  }
}
POST/api/v1/developer/files/upload
Scope: write15 req/min

Upload 3D Model or Media File

Uploads a 3D model (.stl, .obj, .3mf, .step, .zip, etc.) or image/video file (.jpg, .png, .webp, .mp4) via multipart/form-data. Use the returned path/url in the files array when creating or updating a product.

Parametri
filefile (multipart)Obbligatorio
File to upload (Max: 500 MB)
categorystring (form)Obbligatorio
"models" (3D printable files) or "images" (cover/gallery media)
Esempio Risposta (JSON)
{
  "success": true,
  "data": {
    "path": "private/stores/42/models/a91f38c2_crystal_dragon_v2.3mf.enc",
    "url": "private/stores/42/models/a91f38c2_crystal_dragon_v2.3mf.enc",
    "original_name": "crystal_dragon_v2.3mf",
    "size_kb": 18420,
    "category": "models"
  }
}
POST/api/v1/developer/products
Scope: write30 req/min

Create a New Product

Creates a new 3D model product in your store by linking file paths obtained from /api/v1/developer/files/upload.

Esempio Richiesta (JSON)
{
  "title": "Articulated Crystal Dragon v2",
  "description": "<p>High-detail print-in-place crystal dragon. Tested on Bambu Lab X1C & Prusa MK4.</p>",
  "price": 149.90,
  "discount_price": 99.90,
  "category_id": 1,
  "sku": "CFD-DRG-002",
  "status": "published",
  "is_ai_generated": false,
  "license_type": "personal",
  "license_fee": 0,
  "tags": ["dragon", "articulated", "fantasy", "print-in-place"],
  "collection_ids": [12],
  "files": [
    {
      "file_url": "private/stores/42/models/a91f38c2_crystal_dragon_v2.3mf.enc",
      "file_type": "model",
      "display_name": "crystal_dragon_v2.3mf",
      "file_size_kb": 18420,
      "is_primary": true
    },
    {
      "file_url": "https://cdn.3dligo.com/public/stores/42/images/cover_render.webp",
      "file_type": "image",
      "display_name": "cover_render.webp",
      "file_size_kb": 420,
      "is_primary": true
    }
  ]
}
Esempio Risposta (JSON)
{
  "success": true,
  "data": {
    "id": 1042,
    "title": "Articulated Crystal Dragon v2",
    "slug": "articulated-crystal-dragon-v2-1731628900",
    "status": "published",
    "message": "Product created successfully"
  }
}
PUT/api/v1/developer/products/:id
Scope: write30 req/min

Update an Existing Product

Updates metadata, pricing, status, tags, or attached files of an existing product owned by your store.

Esempio Richiesta (JSON)
{
  "title": "Articulated Crystal Dragon v2.1 (Enhanced Hinges)",
  "price": 149.90,
  "discount_price": 79.90,
  "status": "published",
  "tags": ["dragon", "articulated", "bambu-studio"]
}
Esempio Risposta (JSON)
{
  "success": true,
  "data": {
    "id": 1042,
    "message": "Product updated successfully"
  }
}
POST/api/v1/developer/products/:id/versions
Scope: write30 req/min

Publish New Product Version

Publishes a new semantic version and changelog for an existing product and optionally attaches newly uploaded model files.

Esempio Richiesta (JSON)
{
  "version_number": "2.1.0",
  "changelog": "Strengthened tail joints and added pre-supported Chitubox resin file.",
  "files": [
    {
      "file_url": "private/stores/42/models/f82b19d4_dragon_v2_1_resin.3mf.enc",
      "file_type": "model",
      "display_name": "dragon_v2_1_resin.3mf",
      "file_size_kb": 24100,
      "is_primary": false
    }
  ]
}
Esempio Risposta (JSON)
{
  "success": true,
  "data": {
    "version_id": 315,
    "product_id": 1042,
    "version_number": "2.1.0",
    "message": "New product version published"
  }
}
DELETE/api/v1/developer/products/:id
Scope: write30 req/min

Delete Store Product

Deletes a product owned by your store (or safely archives it if previously purchased by customers).

Esempio Risposta (JSON)
{
  "success": true,
  "data": {
    "id": 1042,
    "action": "deleted",
    "message": "Product removed successfully"
  }
}

Codici di Stato HTTP ed Errori

200 / 201 OK

Request completed successfully.

400 Bad Request

Invalid JSON payload, unsupported file format, or API key sent in URL query string.

401 Unauthorized

Missing, invalid, expired, or revoked API key.

403 Forbidden

API key lacks required permission (e.g., write scope not enabled) or IP restriction.

413 / 507 Quota

File exceeds 500 MB limit or store storage quota is full.

429 Too Many Requests

Rate limit exceeded. Wait for the duration in the Retry-After header.