3DLIGO 개발자 API 및 AI 연동 가이드

코드 또는 AI 어시스턴트로 3D 스토어를 자동화하세요

3DLigo REST API를 사용하여 3D 모델(.stl, .3mf, .obj, .step 등)을 대량 업로드하고, 상품을 업데이트하고, 새 버전을 배포하거나 Cursor, Claude, ChatGPT 같은 AI 도구를 스토어에 직접 연결하세요.

기본 URL (Base URL)REST JSON / Multipart
https://3dligo.com/api/v1/developer
인증 방식
Bearer Token / X-API-Key
기본 권한
Read (읽기 기본 선택)
업로드 및 수정
Write (쓰기 - 선택 사항)
지원 파일 형식
STL, 3MF, OBJ, STEP, ZIP + 이미지

3단계로 시작하는 API 사용법

단 몇 분 만에 자체 프로그램이나 AI 코딩 어시스턴트를 스토어에 연결할 수 있습니다.

01

1. API 키 발급받기

store.3dligo.com/settings 페이지의 "API & Developers" 탭으로 이동하세요. 기본으로 "Read(읽기)"가 선택되어 있으며, 모델 업로드 및 상품 수정을 원하시면 "Write(쓰기)"도 체크하여 키를 생성하세요.

02

2. HTTP 헤더에 API 키 추가

발급받은 키를 HTTP 요청 헤더에 "Authorization: Bearer YOUR_API_KEY" 또는 "X-API-Key: YOUR_API_KEY"로 포함해 전송합니다.

03

3. 3D 모델 업로드 및 상품 관리

먼저 /files/upload로 모델과 이미지를 업로드한 뒤, 반환된 파일 경로를 /products에 전달하여 상품을 등록하거나 수정합니다.

인증 방법 (Authentication)

모든 API 요청은 HTTP 헤더에 API 키를 포함해야 합니다:

방법 1 — Authorization Bearer (권장)
Authorization: Bearer ligo_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
방법 2 — X-API-Key 헤더
X-API-Key: ligo_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
⚠ 중요 규칙: URL 파라미터로 API 키를 전송하지 마세요보안을 위해 ?api_key=... 형태의 URL 쿼리 요청은 400 Bad Request로 거부됩니다.

권한 범위 (Scopes) 및 요청 제한

키 생성 시 필요한 권한을 선택할 수 있습니다:

권한 (Scope)기본값분당 제한수행 가능한 작업
read예 (기본 선택)120 / min스토어 프로필, 용량, 상품 목록, 상품 상세, 카테고리 및 컬렉션 조회
write선택 사항30 / min신규 상품 등록, 상품 수정, 버전 추가 및 상품 삭제
uploadWrite 권한에 포함15 / min3D 모델 및 이미지/비디오 파일 업로드 (최대 500 MB)

인기 프로그래밍 언어별 예제 코드

사용 중인 언어를 선택하여 상품 조회, 3D 모델 업로드, 상품 등록 코드를 바로 복사하세요.

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())
✨ AI 자동화 워크플로우

AI 도구 연동하기 (ChatGPT, Claude, Cursor, Copilot)

아래의 AI 시스템 프롬프트를 복사하여 Cursor, Claude Code, ChatGPT에 붙여넣으면 자연어 명령만으로 스토어를 관리할 수 있습니다.

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

AI 어시스턴트 연동 방법

STEP 1스토어 설정(store.3dligo.com/settings)에서 "Read"와 "Write" 권한이 모두 켜진 API 키를 생성합니다.
STEP 2아래의 "AI 시스템 프롬프트"를 복사하여 AI 도구에 붙여넣습니다.
STEP 3AI에게 원하는 작업을 자연어로 지시하세요 (예: "폴더 안의 모든 STL 파일을 내 스토어에 업로드해 줘").
복사해서 바로 쓰는 AI 시스템 프롬프트 (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.

AI에게 요청할 수 있는 명령어 예시

3D 모델 일괄 업로드

"./Models 폴더에 있는 모든 .3mf 및 .stl 파일을 커버 이미지와 함께 내 3DLigo 스토어에 $14.99 가격으로 업로드하고 게시해 줘."

일괄 가격 및 할인 업데이트

"내 3DLigo 스토어의 모든 게시된 상품을 조회하고, 가격이 $10 이상인 모든 상품에 20% 할인가(discount_price)를 적용해 줘."

새 버전 배포하기

"내 스토어에서 'Crystal Dragon' 상품을 찾아 dragon_v2_fixed.3mf 파일을 업로드하고 버전 2.0.0으로 추가해 줘."

전체 API 엔드포인트 레퍼런스

모든 엔드포인트는 인증된 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.

응답 예시 (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.

응답 예시 (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.

응답 예시 (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.

응답 예시 (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.

파라미터
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
응답 예시 (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.

응답 예시 (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.

파라미터
filefile (multipart)필수
File to upload (Max: 500 MB)
categorystring (form)필수
"models" (3D printable files) or "images" (cover/gallery media)
응답 예시 (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.

요청 본문 예시 (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
    }
  ]
}
응답 예시 (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.

요청 본문 예시 (JSON)
{
  "title": "Articulated Crystal Dragon v2.1 (Enhanced Hinges)",
  "price": 149.90,
  "discount_price": 79.90,
  "status": "published",
  "tags": ["dragon", "articulated", "bambu-studio"]
}
응답 예시 (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.

요청 본문 예시 (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
    }
  ]
}
응답 예시 (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).

응답 예시 (JSON)
{
  "success": true,
  "data": {
    "id": 1042,
    "action": "deleted",
    "message": "Product removed successfully"
  }
}

HTTP 상태 및 오류 코드

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.