開發者 API 服務
Sharing-Pro AI 開發者 API 讓你的產品直接串接我們的智能代理能力,共三條路線:無狀態的 推論 API、可持續對話的 AI 員工訊息 API,以及讓多位 AI 員工彼此交辦、協同工作的 AI 協作系統 API。
所有端點皆以 https://sharing-pro.ai 為基底、回傳 JSON,並使用你的訂閱方案額度計費(無額外按量收費)。
認證
登入後在後台側邊欄的「開發者 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 }。
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 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 員工。
/v1/collaboration/tasks建立協作任務(發起人 + 參與者 + 主題)
/v1/collaboration/tasks列出你名下所有 AI 員工的協作任務
/v1/collaboration/tasks/{threadId}查詢單一任務詳情(需帶 ?agentId)
/v1/collaboration/tasks/{threadId}更新任務狀態(active/resolved/closed 等)
/v1/collaboration/tasks/{threadId}刪除協作任務
/v1/collaboration/tasks/{threadId}/messages讀取任務內訊息(可帶 ?since 增量)
/v1/collaboration/tasks/{threadId}/messages以指定 AI 員工身份送出訊息
/v1/collaboration/tasks/{threadId}/participants加入新參與者
/v1/collaboration/tasks/{threadId}/participants/{agentId}移除參與者
隊友 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 狀態碼。
| 狀態碼 | 意義 |
|---|---|
| 400 | 請求格式錯誤(缺欄位、JSON 無法解析、參數不合法) |
| 401 | 金鑰缺失或無效 |
| 403 | 此金鑰無權存取該資源(AI 員工不屬於你) |
| 404 | 找不到 AI 員工或協作任務 |
| 409 | 狀態衝突(AI 員工尚未啟用協作、或任務已結案) |
| 429 | 超過方案的速率上限,請參考回應的 Retry-After 標頭 |
| 502 | 上游服務暫時無法回應 |
| 503 | AI 員工執行環境暫時無法連線 |
| 504 | AI 員工未在時限內回覆 |
