Back to Hub

Public API Reference

Integrate SoulMD Hub programmatically. 100% API-Driven Architecture.

開發者 API 說明文檔

使用者認證與安全帳號 API

POST /api/register

註冊新創作者帳號並自動發配 Secret API Key。內部強化網址安全規範校驗。

檢視請求 JSON 欄體範例 
{
  "username": "developer101",
  "password": "securepassword123",
  "email": "[email protected]"
}
檢視回應 JSON 範例 
{
  "success": true,
  "message": "Account created successfully",
  "api_key": "7f8a9b2c3d4e5f6a7b8c9d0e1f2a3b4c..."
}
POST /api/login

使用者身份驗證。成功後回傳開發者金鑰，並可依要求自動綁定 30 天 Cookie 保持登入狀態。

檢視請求 JSON 欄體範例 
{
  "username": "developer101",
  "password": "securepassword123",
  "remember": true
}
檢視回應 JSON 範例 
{
  "success": true,
  "message": "Login successful",
  "api_key": "7f8a9b2c3d4e5f6a7b8c9d0e1f2a3b4c..."
}
POST /api/change-password 需 Bearer 密鑰認證

安全地變更當前登入使用者的系統密碼。

檢視請求 JSON 欄體範例 
{
  "current_password": "securepassword123",
  "new_password": "brandnewpassword999",
  "confirm_password": "brandnewpassword999"
}
檢視回應 JSON 範例 
{
  "success": true,
  "message": "Password successfully updated!"
}

核心對話與大模型路由引擎 API

GET /api/chat 需 Bearer 密鑰認證 VIP / PRO Only

以無頭（Headless）端遠端查詢指定對話工作階段的歷史紀錄訊息陣列。受權限隔離安全機制保護。

網址參數 (Query params): ?soul_id=1&session_token=random_token_here

檢視回應 JSON 範例 
{
  "success": true,
  "messages": [
    {
      "role": "user",
      "content": "Hello! How can you help me today?"
    },
    {
      "role": "assistant",
      "content": "I am an expert assistant. I can help you with coding and reasoning tasks."
    }
  ]
}
POST /api/chat 需 Bearer 密鑰認證 VIP / PRO Only

遠端發送對話呼叫。系統會自動調度智能雙引擎（純文字投遞 DeepSeek，帶圖片投遞 Together AI 視覺模態）並自動刷新滑動內存。免費或過期帳戶直接阻斷並回傳 403 Forbidden。

進階付費政策： Headless API 整合串接為 VIP 與 PRO 會員專屬。若您的尊貴會員通行證到期，遠端 API 存取權限將自動暫停阻斷，直至完成手動續期為止。

檢視請求 JSON 欄體範例 
{
  "action": "chat",
  "soul_id": 1,
  "session_token": "unique_session_id_123",
  "content": "Can you analyze this architecture diagram?",
  "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...", // Optional Base64 Image
  "is_private": false
}
檢視回應 JSON 範例 
{
  "success": true,
  "reply": "Based on the provided architecture diagram, here is the technical breakdown..."
}

模型資產管理 API (Souls Hub)

GET /api/categories

拉取目前系統白名單允許的所有 AI 適用角色分類、對應的 Slug 別名及前端 Emoji 圖標。

檢視回應 JSON 範例 
{
  "success": true,
  "count": 2,
  "data": [
    { "id": 1, "name": "Developer", "slug": "Developer", "icon": "💻" },
    { "id": 2, "name": "Writer", "slug": "Writer", "icon": "✍️" }
  ]
}
GET /api/souls

分頁撈取、檢索大廳中公開的靈魂模型列表。內部經過極致索引優化。

網址參數 (Query params): ?limit=20&offset=0&q=ai&sort=popular&role=Developer

檢視回應 JSON 範例 
{
  "success": true,
  "count": 1,
  "data": [
    {
      "id": 1,
      "title": "Expert Translator",
      "description": "Translates documents contextually",
      "role": "Translator",
      "domain": "Education",
      "compatibility": "Claude 3.5 Sonnet",
      "file_type": "single_md",
      "like_count": 12,
      "fork_count": 3,
      "created_at": "2026-05-21 12:00:00"
    }
  ]
}
GET /api/soul/{id}

獲取單一模型代碼庫的完整結構、原創內容、知識領域標籤、相容性及社群統計指標。

檢視回應範例 (單一 .md 文件 模式) 
{
  "success": true,
  "data": {
    "id": 1,
    "user_id": 5,
    "title": "Expert Translator",
    "description": "Translates documents contextually",
    "content": "## Identity\nYou are an expert translator...",
    "file_type": "single_md",
    "role": "Translator",
    "domain": "Education",
    "compatibility": "Claude 3.5 Sonnet",
    "is_public": 1,
    "like_count": 12,
    "fork_count": 3,
    "created_at": "2026-05-21 12:00:00"
  }
}
檢視回應範例 (模組化資料夾 JSON 模式) 
{
  "success": true,
  "data": {
    "id": 2,
    "user_id": 5,
    "title": "Advanced Dev Architecture",
    "description": "Full-stack code assistant package layout",
    "content": "{\n  \"SOUL.md\": \"## Identity\\nYou are a senior developer...\",\n  \"STYLE.md\": \"## Voice\\nConcise, code-heavy...\",\n  \"RULES.md\": \"## Hard Rules\\nNever write legacy code...\"\n}",
    "file_type": "full_soul_folder",
    "role": "Developer",
    "domain": "Coding & Dev",
    "compatibility": "GPT-4o",
    "is_public": 1,
    "like_count": 88,
    "fork_count": 15,
    "created_at": "2026-05-21 14:22:10"
  }
}
POST /api/souls 需 Bearer 密鑰認證

發佈與上傳全新智能體。系統會自動檢測並兼容單一 `.md` 文件或模組化多檔案的 JSON 樹狀物件。

重大約束條件： 請求體中的 role 欄位必須嚴格匹配 /api/categories 所回傳的 slug 鍵值。不合規的命名將被系統強制歸類為 'Other'。

檢視請求 JSON 欄體範例 
{
  "title": "Expert Translator",
  "description": "Translates documents contextually",
  "content": "## Identity\nYou are an expert translator...",
  "role": "Translator",
  "domain": "Education",
  "compatibility": "Claude 3.5 Sonnet"
}
檢視回應 JSON 範例 
{
  "success": true,
  "message": "Soul created successfully",
  "id": 42,
  "url": "https://soulmd-hub.ysk.hk/soul/42"
}
PUT /api/soul/{id} 需 Bearer 密鑰認證

更新已存在的智能體佈局。系統會自動觸發觸發器，將舊有結構拷貝快照備份至 `soul_versions` 版本歷史表內。

檢視請求 JSON 欄體範例 
{
  "title": "Expert Translator v2",
  "description": "Updated translation engine",
  "content": "## Identity\nYou are...",
  "role": "Translator",
  "domain": "Education",
  "compatibility": "Claude 3.5 Sonnet",
  "is_public": 1
}
檢視回應 JSON 範例 
{
  "success": true,
  "message": "Soul updated successfully"
}
DELETE /api/soul/{id} 需 Bearer 密鑰認證

永久刪除指定的靈魂模型，並自動解耦清算相關聯的知識領域標籤之使用率計數器。

檢視回應 JSON 範例 
{
  "success": true,
  "message": "Soul deleted successfully"
}

創作者主頁與社群互動 API

GET /api/profile

查詢指定創作者的全局公開看板數據（包含獲讚、被分叉總數）以及他名下的公開作品矩陣。

網址參數 (Query params): ?username=developer101

檢視回應 JSON 範例 
{
  "success": true,
  "user": {
    "username": "developer101",
    "joined_at": "2026-05-20 10:00:00"
  },
  "stats": {
    "total_souls": 5,
    "total_likes": 24,
    "total_forks": 8
  },
  "souls": [
    {
      "id": 1,
      "title": "Expert Translator",
      "description": "Translates documents...",
      "role": "Translator",
      "domain": "Education",
      "compatibility": "Claude 3.5 Sonnet",
      "file_type": "single_md",
      "like_count": 12,
      "fork_count": 3,
      "created_at": "2026-05-21 12:00:00"
    }
  ]
}
GET /api/versions

撈取指定模型歷史版本時間線檔案庫。內部具備嚴格的越權保護機制。

網址參數 (Query params): ?soul_id={id}

檢視回應 JSON 範例 
{
  "success": true,
  "count": 1,
  "data": [
    {
      "id": 12,
      "soul_id": 1,
      "title": "Expert Translator v1",
      "content": "## Identity\nYou are...",
      "edited_at": "2026-05-21 15:30:00"
    }
  ]
}
POST /api/versions 需 Bearer 密鑰認證

執行指令將目前線上的智能體結構內容，秒級還原（Rollback）到指定的歷史版本時間標記點。

檢視請求 JSON 欄體範例 
{
  "soul_id": 1,
  "version_id": 5
}
檢視回應 JSON 範例 
{
  "success": true,
  "message": "Version restored successfully"
}
POST /api/fork 需 Bearer 密鑰認證

克隆（Clone）一個公開的模型，分叉複製一份完全獨立的全新複本到您自己的創作者工作區。

檢視請求 JSON 欄體範例 
{
  "soul_id": 1
}
檢視回應 JSON 範例 
{
  "success": true,
  "new_soul_id": 43,
  "url": "https://soulmd-hub.ysk.hk/soul/43",
  "message": "Soul forked successfully!"
}
POST /api/like 需 Bearer 密鑰認證

切換讚好與取消讚好狀態。資料庫套用唯一約束，回傳最新按讚狀態布林值。

檢視請求 JSON 欄體範例 
{
  "soul_id": 1
}
檢視回應 JSON 範例 
{
  "success": true,
  "liked": true,
  "message": "Soul liked successfully"
}
POST /api/rate 需 Bearer 密鑰認證

進行 1 至 5 星社交評分。重複提交會覆蓋舊紀錄，回傳全站最新即時平均星數與總評分人數。

檢視請求 JSON 欄體範例 
{
  "soul_id": 1,
  "rating": 5
}
檢視回應 JSON 範例 
{
  "success": true,
  "message": "Rating submitted successfully",
  "avg_rating": 4.5,
  "total_ratings": 18
}