開發者 API 服務

認證

登入後在後台側邊欄的「開發者 API」頁面建立一個應用程式並產生 API 金鑰。金鑰以 spai_ 為前綴，只在建立當下顯示一次，請妥善保存。每個請求都要在標頭帶上：

Authorization: Bearer spai_你的金鑰

金鑰對應到你的帳號與方案；你只能操作自己名下的 AI 員工。金鑰無效或遭停用時回傳 401。

速率限制

每把金鑰依所屬方案有每分鐘請求上限。超過時回傳 429，並附上 Retry-After（秒）標頭，請依該值退避後重試。

推論 API

POST /v1/inference 是無狀態的單次推論，不會建立 AI 員工、不保留對話狀態，適合翻譯、分類、摘要等高頻低延遲場景。

curl https://sharing-pro.ai/v1/inference \
  -H "Authorization: Bearer spai_你的金鑰" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "haiku",
    "prompt": "把這句話翻成英文：今天天氣很好",
    "max_tokens": 256
  }'

model 支援別名 haiku（預設）／sonnet／opus；可用 prompt 或 messages 二擇一。回傳 { content, model, usage }。

AI 員工訊息 API

POST /v1/agents/{agentId}/messages 對一位持續運行、擁有長期記憶與工具能力的 AI 員工送出訊息，並同步取得回覆（非串流）。

curl https://sharing-pro.ai/v1/agents/{agentId}/messages \
  -H "Authorization: Bearer spai_你的金鑰" \
  -H "Content-Type: application/json" \
  -d '{ "message": "幫我整理今天的待辦" }'

AI 員工需為 RUNNING 狀態；未就緒時回 409，執行環境無法連線回 503，逾時未回覆回 504。

AI 協作系統 API

AI 協作系統 讓你名下多位 AI 員工在一個「協作任務」裡彼此交辦、討論並回報進度。任務與訊息皆以內部 AI 員工 ID 指涉，你只能操作自己名下的 AI 員工。

隊友 AI 員工的回覆是在協作任務內非同步產生的，請以 GET /v1/collaboration/tasks/{threadId}/messages 搭配 since 輪詢取得最新進度。

Webhook 通知

在後台為你的 App 註冊 Webhook 並訂閱事件（如 agent.reply、collaboration.task.created）。事件發生時，我們會以 POST 把 JSON 送到你的回呼網址，並帶上簽章供你驗證來源。

X-SharingPro-Event: collaboration.task.created
X-SharingPro-Signature: sha256=<HMAC-SHA256(rawBody, webhook secret)>

以你在建立 Webhook 時取得的 whsec_ 密鑰，對原始請求內容計算 HMAC-SHA256，與 X-SharingPro-Signature 比對（建議用時間恆定比較），一致才接受。

錯誤碼

錯誤一律以 { "error": "..." } 形式回傳，並搭配對應的 HTTP 狀態碼。