3DLigo REST API를 사용하여 3D 모델(.stl, .3mf, .obj, .step 등)을 대량 업로드하고, 상품을 업데이트하고, 새 버전을 배포하거나 Cursor, Claude, ChatGPT 같은 AI 도구를 스토어에 직접 연결하세요.
단 몇 분 만에 자체 프로그램이나 AI 코딩 어시스턴트를 스토어에 연결할 수 있습니다.
store.3dligo.com/settings 페이지의 "API & Developers" 탭으로 이동하세요. 기본으로 "Read(읽기)"가 선택되어 있으며, 모델 업로드 및 상품 수정을 원하시면 "Write(쓰기)"도 체크하여 키를 생성하세요.
발급받은 키를 HTTP 요청 헤더에 "Authorization: Bearer YOUR_API_KEY" 또는 "X-API-Key: YOUR_API_KEY"로 포함해 전송합니다.
먼저 /files/upload로 모델과 이미지를 업로드한 뒤, 반환된 파일 경로를 /products에 전달하여 상품을 등록하거나 수정합니다.
모든 API 요청은 HTTP 헤더에 API 키를 포함해야 합니다:
키 생성 시 필요한 권한을 선택할 수 있습니다:
| 권한 (Scope) | 기본값 | 분당 제한 | 수행 가능한 작업 |
|---|---|---|---|
| read | 예 (기본 선택) | 120 / min | 스토어 프로필, 용량, 상품 목록, 상품 상세, 카테고리 및 컬렉션 조회 |
| write | 선택 사항 | 30 / min | 신규 상품 등록, 상품 수정, 버전 추가 및 상품 삭제 |
| upload | Write 권한에 포함 | 15 / min | 3D 모델 및 이미지/비디오 파일 업로드 (최대 500 MB) |
사용 중인 언어를 선택하여 상품 조회, 3D 모델 업로드, 상품 등록 코드를 바로 복사하세요.
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())아래의 AI 시스템 프롬프트를 복사하여 Cursor, Claude Code, 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."./Models 폴더에 있는 모든 .3mf 및 .stl 파일을 커버 이미지와 함께 내 3DLigo 스토어에 $14.99 가격으로 업로드하고 게시해 줘."
"내 3DLigo 스토어의 모든 게시된 상품을 조회하고, 가격이 $10 이상인 모든 상품에 20% 할인가(discount_price)를 적용해 줘."
"내 스토어에서 'Crystal Dragon' 상품을 찾아 dragon_v2_fixed.3mf 파일을 업로드하고 버전 2.0.0으로 추가해 줘."
모든 엔드포인트는 인증된 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)필수categorystring (form)필수{
"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.