واجهة برمجة تطبيقات 3DLIGO وتكامل الذكاء الاصطناعي

قم بأتمتة متجرك ثلاثي الأبعاد بالكود أو مساعدي الذكاء الاصطناعي

استخدم واجهة 3DLigo REST API لرفع النماذج ثلاثية الأبعاد (.stl, .3mf, .obj, .step) دفعة واحدة، وتحديث المنتجات، ونشر الإصدارات، أو ربط أدوات الذكاء الاصطناعي مثل Cursor وClaude وChatGPT بمتجرك مباشرة.

الرابط الأساسي (Base URL)REST JSON / Multipart
https://3dligo.com/api/v1/developer
المصادقة
Bearer Token / X-API-Key
الصلاحية الافتراضية
Read (قراءة)
الرفع والتحديث
Write (كتابة - اختياري)
الصيغ المدعومة
STL, 3MF, OBJ, STEP, ZIP + الصور

كيف يعمل في 3 خطوات بسيطة

اربط متجرك بتطبيقاتك الخاصة أو بمساعد الذكاء الاصطناعي خلال دقائق.

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 ثم مرر المسارات الناتجة إلى /products لإنشاء المنتج أو تحديثه.

المصادقة (Authentication)

يجب إرسال مفتاح API في ترويسة HTTP مع كل طلب:

الخيار 1 — Authorization Bearer (موصى به)
Authorization: Bearer ligo_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
الخيار 2 — ترويسة X-API-Key
X-API-Key: ligo_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
⚠ قاعدة هامة: لا ترسل المفتاح داخل الرابط URLيتم رفض أي طلب يحتوي على ?api_key=... في الرابط برمز 400 Bad Request.

الصلاحيات (Scopes) وحدود الطلبات

اختر الصلاحيات المناسبة عند إنشاء المفتاح:

الصلاحيةافتراضيالحد في الدقيقةالعمليات المسموحة
readنعم (افتراضي)120 / minعرض بيانات المتجر والمنتجات والتفاصيل والتصنيفات والمجموعات
writeاختياري30 / minإنشاء المنتجات وتحديثها وإضافة الإصدارات وحذف المنتجات
uploadمتاح مع Write15 / minرفع ملفات النماذج ثلاثية الأبعاد والصور (حتى 500 ميجابايت)

أمثلة برمجية بأشهر لغات البرمجة

اختر لغة البرمجة المفضلة لديك لنسخ الكود الجاهز.

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())
✨ الأتمتة بالذكاء الاصطناعي

اربط أدوات الذكاء الاصطناعي (ChatGPT, Claude, Cursor, Copilot)

انسخ أمر النظام الجاهز أدناه والصقه في Cursor أو Claude أو ChatGPT لإدارة متجرك باللغة الطبيعية.

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

كيفية الاستخدام مع الذكاء الاصطناعي

STEP 1أنشئ مفتاح API بصلاحيتي "Read" و"Write" من إعدادات المتجر.
STEP 2انسخ "أمر النظام للذكاء الاصطناعي" أدناه والصقه في أداة الذكاء الاصطناعي.
STEP 3اطلب من الذكاء الاصطناعي تنفيذ ما تريد بلغتك العادية.
أمر النظام الجاهز للذكاء الاصطناعي (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.

أمثلة لأوامر يمكنك طلبها من الذكاء الاصطناعي

رفع جماعي للنماذج ثلاثية الأبعاد

"ارفع جميع ملفات .3mf و.stl الموجودة في مجلد ./Models مع صور الغلاف إلى متجري في 3DLigo بسعر 14.99 دولار."

تحديث الأسعار والخصومات دفعة واحدة

"اعرض جميع منتجات متجري في 3DLigo وطبّق خصماً بنسبة 20% على جميع المنتجات التي يزيد سعرها عن 10 دولارات."

نشر إصدار جديد للمنتج

"ابحث عن منتج 'Crystal Dragon' وارفع ملف dragon_v2_fixed.3mf وأضفه كإصدار 2.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.

مثال الاستجابة (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.

المعاملات (Parameters)
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.

المعاملات (Parameters)
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.