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 ステップで使い始める

数分で独自スクリプトや AI アシスタントをストアに接続できます。

01

1. API キーを発行する

store.3dligo.com/settings の「API & Developers」タブを開きます。デフォルトで「Read」が選択されています。モデルのアップロードや商品更新を行う場合は「Write」にもチェックを入れて作成してください。

02

2. HTTP ヘッダーにキーを設定する

発行されたキーを HTTP リクエストヘッダーの "Authorization: Bearer YOUR_API_KEY" または "X-API-Key: YOUR_API_KEY" に指定して送信します。

03

3. モデルのアップロードと商品管理

まず /files/upload で 3D モデルと画像をアップロードし、返却されたファイルパスを使って /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 として拒否されます。

権限スコープとレート制限

用途に合わせてキーの権限を選択できます:

スコープデフォルト制限(毎分)可能な操作
readはい(標準)120 / minストア情報、商品一覧、商品詳細、カテゴリー、コレクションの取得
write任意選択30 / min商品の新規作成、更新、新バージョンの追加、削除
uploadWrite 権限で利用可能15 / min3D モデルおよび画像・動画ファイルのアップロード(最大 500 MB)

主要プログラミング言語での実装サンプル

お使いの言語を選択して、すぐに使えるサンプルコードをコピーできます。

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ストア設定で「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.