3DLIGO 开发者 API 与 AI 集成指南

使用代码或 AI 助手 自动化管理您的 3D 商店

通过 3DLigo REST API 批量上传 3D 模型(.stl、.3mf、.obj、.step 等)、更新商品信息、发布新版本,或将 Cursor、Claude、ChatGPT 等 AI 工具直接连接到您的商店。

基础请求地址 (Base URL)REST JSON / Multipart
https://3dligo.com/api/v1/developer
身份验证方式
Bearer Token / X-API-Key
默认权限
Read(只读,默认勾选)
上传与修改权限
Write(写入,可选)
支持的文件格式
STL, 3MF, OBJ, STEP, ZIP + 图片/视频

只需 3 步即可快速上手

几分钟内即可将您的商店连接到自定义脚本、Blender 插件或 AI 编程助手。

01

1. 生成 API 密钥

前往 store.3dligo.com/settings 的“API & Developers”标签页。默认勾选“Read(读取)”,如需上传模型或创建/更新商品,请同时勾选“Write(写入)”。

02

2. 在 HTTP 请求头中携带密钥

复制生成的 ligo_live_... 密钥,并在请求头中添加 "Authorization: Bearer YOUR_API_KEY" 或 "X-API-Key: YOUR_API_KEY"。

03

3. 上传模型并管理商品

先通过 /files/upload 接口上传 3D 模型和封面图,再将返回的文件路径提交至 /products 创建或更新商品。

身份验证 (Authentication)

所有 API 请求都必须在 HTTP Header 中包含您的 API 密钥,支持以下两种格式:

方式 1 — Authorization Bearer(推荐)
Authorization: Bearer ligo_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
方式 2 — X-API-Key 请求头
X-API-Key: ligo_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
⚠ 重要规则:请勿在 URL 参数中传递 API 密钥出于安全考虑,在 URL 查询参数(如 ?api_key=...)中传递密钥将返回 400 Bad Request。

权限范围 (Scopes) 与速率限制

创建密钥时可根据需求勾选权限:

权限默认设置速率限制可执行的操作
read是(默认勾选)120 / min查看商店信息、存储配额、商品列表、商品详情、分类与合集
write可选30 / min创建新商品、更新商品、发布新版本以及删除商品
upload包含在 Write 权限中15 / min流式上传 3D 模型与图片/视频文件(单文件最大 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 系统提示词(Prompt)并粘贴到 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 Key。
STEP 2复制下方的“AI 系统提示词”并发送给您的 AI 工具(Cursor / Claude / ChatGPT)。
STEP 3直接用自然语言告诉 AI 您想执行的操作(例如:“把文件夹里的所有 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 的所有商品应用 8 折优惠 (discount_price)。”

发布模型新版本

“找到我的 ‘Crystal Dragon’ 商品,上传 dragon_v2_fixed.3mf 并将其作为 v2.0.0 版本发布。”

API 接口参考手册 (Endpoints)

所有接口仅对当前 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.

响应示例 (Response 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.

响应示例 (Response 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.

响应示例 (Response 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.

响应示例 (Response 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
响应示例 (Response 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.

响应示例 (Response 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)
响应示例 (Response 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.

请求体示例 (Request 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
    }
  ]
}
响应示例 (Response 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.

请求体示例 (Request JSON)
{
  "title": "Articulated Crystal Dragon v2.1 (Enhanced Hinges)",
  "price": 149.90,
  "discount_price": 79.90,
  "status": "published",
  "tags": ["dragon", "articulated", "bambu-studio"]
}
响应示例 (Response 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.

请求体示例 (Request 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
    }
  ]
}
响应示例 (Response 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).

响应示例 (Response 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.