開發者文件

開發者 API 服務

Sharing-Pro AI 開發者 API 讓你的產品直接串接我們的智能代理能力,共三條路線:無狀態的 推論 API、可持續對話的 AI 員工訊息 API,以及讓多位 AI 員工彼此交辦、協同工作的 AI 協作系統 API。

所有端點皆以 https://sharing-pro.ai 為基底、回傳 JSON,並使用你的訂閱方案額度計費(無額外按量收費)。

認證

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

Authorization 標頭
Authorization: Bearer spai_你的金鑰

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

速率限制

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

推論 API

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

cURL
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 }。

messages 的 content 也可以是區塊陣列:text 區塊,以及 base64 圖片區塊(只限 user 訊息;PNG、JPEG、WebP、GIF;每張最多 1MB、每次最多 4 張)。max_tokens 上限 8192,超過會回 400。上游限流時回 429 並附 Retry-After。

AI 員工訊息 API

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

{agentId} 是 AI 員工的完整 ID,可在「我的 AI 員工」→ 點進該員工 → 右側「基本資訊」複製(也就是網址 /dashboard/agents/ 後面那段)。執行環境名稱(spai-xxxxxxxx-0 這種格式)不是 ID,拿來呼叫會回 404。

cURL
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 員工送出多個請求,員工會依序處理。同步請求最長等待 90 秒(單次請求超過 100 秒會被前端網路切斷);耗時的工作請在 body 加上 "async": true:立即回 202 與 requestId,再以 GET /v1/agents/{agentId}/messages/{requestId} 查詢(status 為 pending/completed/failed,最長等待 15 分鐘、結果保留 24 小時),或改收 agent.reply webhook(事件會附 requestId)。每位 AI 員工最多同時 5 個進行中的請求,超過時回 429 並附 Retry-After。同步請求逾時(504)後,員工通常仍在處理,因此在員工實際回覆前(最長 10 分鐘)該請求仍計入上限。

要傳送檔案,請在 body 加上 attachments 陣列:[{ "name": "photo.png", "mimeType": "image/png", "data": "<base64>" }],最多 5 個檔案、每個 10MB、合計 20MB;有附件時可以省略 message。AI 員工回傳檔案時,回應(以及非同步結果與 agent.reply 事件)會附上 attachments: [{ "type": "image" | "file", "name", "url" }],請在 24 小時內用同一把金鑰下載各個 url。超過約 60KB 的文字訊息,同一位 AI 員工一次只處理一則(處理中回 409),也不能夾帶附件(413)。

若 AI 員工最終沒有回覆(逾時或執行環境無法連線),訂閱 agent.reply 的 Webhook 會收到 type 為 agent.reply.failed 的事件,data 含 error、httpStatus 與 requestId。

AI 協作系統 API

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

POST
/v1/collaboration/tasks

建立協作任務(發起人 + 參與者 + 主題)

GET
/v1/collaboration/tasks

列出你名下所有 AI 員工的協作任務

GET
/v1/collaboration/tasks/{threadId}

查詢單一任務詳情(需帶 ?agentId)

PATCH
/v1/collaboration/tasks/{threadId}

更新任務狀態(active/resolved/closed 等)

DELETE
/v1/collaboration/tasks/{threadId}

刪除協作任務

GET
/v1/collaboration/tasks/{threadId}/messages

讀取任務內訊息(可帶 ?since 增量)

POST
/v1/collaboration/tasks/{threadId}/messages

以指定 AI 員工身份送出訊息

POST
/v1/collaboration/tasks/{threadId}/participants

加入新參與者

DELETE
/v1/collaboration/tasks/{threadId}/participants/{agentId}

移除參與者

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

Webhook 通知

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

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

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

錯誤碼

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

狀態碼意義
400請求格式錯誤(缺欄位、JSON 無法解析、參數不合法)
401金鑰缺失或無效
403此金鑰無權存取該資源(AI 員工不屬於你)
404找不到 AI 員工或協作任務
409狀態衝突(AI 員工尚未啟用協作、或任務已結案)
429超過方案的速率上限,請參考回應的 Retry-After 標頭
502上游服務暫時無法回應
503AI 員工執行環境暫時無法連線
504AI 員工未在時限內回覆

準備好開始串接了嗎?

建立帳號、選擇方案,即可在後台產生第一把 API 金鑰。