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.
Collega il tuo negozio ai tuoi script o al tuo assistente IA in pochi minuti.
Vai su store.3dligo.com/settings nella scheda "API & Developers". "Read" è selezionato di default; spunta anche "Write" per caricare modelli e aggiornare i prodotti.
Includi la chiave nelle richieste HTTP tramite "Authorization: Bearer TUA_API_KEY" o "X-API-Key: TUA_API_KEY".
Carica i file tramite /files/upload e usa i percorsi restituiti su /products per creare o aggiornare i prodotti.
Autentica ogni richiesta inviando la chiave API negli header HTTP:
Scegli i permessi necessari durante la creazione della chiave:
| Permesso | Predefinito | Limite | Operazioni Consentite |
|---|---|---|---|
| read | Sì (Default) | 120 / min | Elenca profilo negozio, prodotti, dettagli, categorie e collezioni |
| write | Opzionale | 30 / min | Crea, aggiorna, aggiungi versioni ed elimina prodotti |
| upload | Incluso con Write | 15 / min | Carica modelli 3D e immagini/video (fino a 500 MB) |
Scegli il tuo linguaggio di programmazione e copia il codice pronto all'uso.
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())Copia il prompt di sistema qui sotto in Cursor, Claude o ChatGPT per gestire il tuo negozio in linguaggio naturale.
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."Carica tutti i file .3mf e .stl dalla cartella ./Models insieme alle immagini di copertina sul mio negozio 3DLigo al prezzo di 14,99 €."
"Elenca tutti i prodotti del mio negozio 3DLigo e applica uno sconto del 20% a quelli sopra i 10 €."
"Trova il prodotto 'Crystal Dragon', carica dragon_v2_fixed.3mf e aggiungilo come versione 2.0.0."
Tutti gli endpoint operano esclusivamente sul negozio associato alla tua chiave API.
/api/v1/developer/storeReturns the authenticated store profile, approval status, total product count, and storage quota usage.
{
"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"]
}
}
}/api/v1/developer/categoriesReturns all active 3DLigo marketplace categories (IDs, names, and slugs) for use when creating or updating products.
{
"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
}
]
}/api/v1/developer/collectionsLists custom collections belonging to your store. Pass these IDs in collection_ids when creating or updating products.
{
"success": true,
"data": [
{
"id": 12,
"title": "2026 Mech Series",
"slug": "2026-mech-series"
}
]
}/api/v1/developer/productsLists products belonging to your store with pagination, status filter, and search query.
pageintegerlimitintegerstatusstringqstring{
"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
}
}
}/api/v1/developer/products/:idRetrieves full details of a single store product including uploaded 3D model files, gallery images, tags, and version history.
{
"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"
}
]
}
}/api/v1/developer/files/uploadUploads 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.
filefile (multipart)Obbligatoriocategorystring (form)Obbligatorio{
"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"
}
}/api/v1/developer/productsCreates a new 3D model product in your store by linking file paths obtained from /api/v1/developer/files/upload.
{
"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
}
]
}{
"success": true,
"data": {
"id": 1042,
"title": "Articulated Crystal Dragon v2",
"slug": "articulated-crystal-dragon-v2-1731628900",
"status": "published",
"message": "Product created successfully"
}
}/api/v1/developer/products/:idUpdates metadata, pricing, status, tags, or attached files of an existing product owned by your store.
{
"title": "Articulated Crystal Dragon v2.1 (Enhanced Hinges)",
"price": 149.90,
"discount_price": 79.90,
"status": "published",
"tags": ["dragon", "articulated", "bambu-studio"]
}{
"success": true,
"data": {
"id": 1042,
"message": "Product updated successfully"
}
}/api/v1/developer/products/:id/versionsPublishes a new semantic version and changelog for an existing product and optionally attaches newly uploaded model files.
{
"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
}
]
}{
"success": true,
"data": {
"version_id": 315,
"product_id": 1042,
"version_number": "2.1.0",
"message": "New product version published"
}
}/api/v1/developer/products/:idDeletes a product owned by your store (or safely archives it if previously purchased by customers).
{
"success": true,
"data": {
"id": 1042,
"action": "deleted",
"message": "Product removed successfully"
}
}Request completed successfully.
Invalid JSON payload, unsupported file format, or API key sent in URL query string.
Missing, invalid, expired, or revoked API key.
API key lacks required permission (e.g., write scope not enabled) or IP restriction.
File exceeds 500 MB limit or store storage quota is full.
Rate limit exceeded. Wait for the duration in the Retry-After header.