回到首頁

API 參考文檔

以程式化方式整合 SoulMD Hub。100% API 驅動架構。

開發者 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!"
}
POST /api/bind-wallet 需 Bearer 密鑰認證

將 Web3 NEAR 錢包綁定至當前帳號。為防止身份偽造，必須攜帶有效的 Ed25519 密碼學簽章 Payload。此操作不可逆。

檢視請求 JSON 欄體範例 
{
  "action": "bind",
  "wallet": "yanshekki.near",
  "public_key": "ed25519:G1...",
  "signature": "L/xN...",
  "message": "soulmd_auth:1716330000000"
}
檢視回應 JSON 範例 
{
  "success": true,
  "message": "Wallet bound successfully!"
}
POST /api/wallet-login

透過 Web3 錢包靜默登入。必須傳入以本地錢包金鑰簽署的 Ed25519 密碼學防偽簽章。若錢包已綁定則核發安全會話。

檢視請求 JSON 欄體範例 
{
  "account_id": "yanshekki.near",
  "public_key": "ed25519:G1...",
  "signature": "L/xN...",
  "message": "soulmd_auth:1716330000000"
}
檢視回應 JSON 範例 
{
  "success": true
}

核心對話與大模型路由引擎 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",
      "sender_name": "developer101",
      "content": "Hello! How can you help me today?"
    },
    {
      "role": "assistant",
      "sender_name": "AI Assistant",
      "content": "I am an expert assistant. I can help you with coding and reasoning tasks."
    }
  ]
}
GET /api/my-chats 需 Bearer 密鑰認證

獲取當前登入用戶所有活躍的歷史對話列表，以及系統自動壓縮的記憶體摘要紀錄。

檢視回應 JSON 範例 
{
  "success": true,
  "sessions": [
    {
      "session_token": "unique_session_id_123",
      "soul_id": 1,
      "summary": "User asked about architecture layout...",
      "last_updated": "2026-05-21 14:00:00"
    }
  ]
}
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...", 
  "is_private": false
}
檢視回應 JSON 範例 
{
  "success": true,
  "reply": "Based on the provided architecture diagram, here is the technical breakdown...",
  "sender_name": "AI Assistant"
}
POST /api/self-chat 需 Bearer 密鑰認證 BYOK Active

無狀態 BYOK 代理端點。使用用戶儲存於資料庫的加密專屬金鑰。此端點不扣除平台每日額度，但嚴格執行 Web3 NFT 門禁檢查。

檢視請求 JSON 欄體範例 
{
  "soul_id": 2,
  "session_token": "byok_session_token_xyz",
  "content": "Execute high-concurrency trace optimization patterns.",
  "image": null,
  "is_private": true
}
檢視回應 JSON 範例 
{
  "success": true,
  "reply": "Optimizing memory structures using stateless concurrent relays...",
  "sender_name": "AI Assistant"
}
GET /api/chat-sync

即時多人在線同步 API。驗證客戶端連線心跳、追蹤同一個聊天室內的在線人數，並使用 Delta Sync 技術增量下發附帶發送者名稱的新訊息。

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

檢視回應 JSON 範例 
{
  "success": true,
  "online_count": 2,
  "new_messages": [
    {
      "id": 143,
      "role": "user",
      "sender_name": "Anonymous #E5A1",
      "content": "Is anyone else monitoring this cluster thread?"
    }
  ]
}

AI 小程式 (Mini Apps)

GET /api/apps

列出策展中的表單式 AI 小程式（或以 ?slug= 取得表單 schema 與主題關鍵字搜尋到的公開 Soul 列表）。Detail 只含 title/description 等介紹，不含提示詞原文。可選參數：category、q。

網址參數 (Query params): ?category=destiny&q=name&slug=name-advisor

檢視回應 JSON 範例 
{
  "success": true,
  "count": 1,
  "data": [
    {
      "slug": "name-advisor",
      "icon": "fa-signature",
      "category": "destiny",
      "title": "Name Advisor",
      "description": "Chinese naming / rename suggestions…",
      "badge": "popular",
      "field_count": 5,
      "search_keywords": "改名 命名 naming"
    }
  ]
}
POST /api/apps Session 或 API 金鑰

校驗小程式表單與 soul_id（必須為符合該 app 主題關鍵字的公開非 NFT Soul）。回傳格式化訊息 content，供前端跳轉 /chat/{soul_id}/{session}。本端點不呼叫 LLM；由 Chat API 套用方案限制並生成回覆。

檢視請求 JSON 欄體範例 
{
  "slug": "name-advisor",
  "soul_id": 7303,
  "fields": {
    "surname": "Chen",
    "gender": "female",
    "birth_datetime": "1989-09-01 06:00",
    "preferences": "gentle, wood/fire",
    "count": "3"
  }
}
檢視回應 JSON 範例 
{
  "success": true,
  "slug": "name-advisor",
  "soul_id": 7303,
  "content": "Surname: Chen\nGender style: Feminine\n…",
  "chat_path": "/chat/7303"
}

模型資產管理 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
}