API 串接 & API 列表¶

API 串接¶

每一個 API 請求都必須包含有效的 API 金鑰。請在 Authorization 標頭中加入以下格式的金鑰

Authorization: Bearer <your-api-key>

PrivAI 支援兩種類型的 API Key：

Master Key：具有管理者權限，可跨租戶檢視與管理資料，也可呼叫 API Key 管理相關 API。
租戶 Key / Tenant Key：提供給單一客戶或單一租戶使用，只能存取該 API Key 所屬租戶的資料。

備註：

原本由系統環境變數設定的 SECRET_KEY 機制仍保留，並在此架構下作為 Master Key 使用。
Tenant Key 的呼叫方式與既有 API 完全相同，僅需將原本的金鑰替換為客戶專屬 API Key。
當 API Key 已過期、被停用或格式不正確時，系統將拒絕請求並回傳對應錯誤碼。

API Key 類型與權限說明¶

PrivAI 使用 API Key 作為身份驗證與資料範圍控制的基礎。不同類型的 API Key 對應不同的權限與資料可見範圍。

Key 類型說明

類型	說明
Master Key	系統管理用金鑰，可檢視所有租戶資料，並管理租戶Key
Tenant Key	單一租戶專屬金鑰，只能存取自身租戶資料

權限差異

功能	Master Key	租戶 Key
呼叫既有 PrivAI API	支援	支援
檢視所有租戶資料	支援	不支援
建立 API Key	支援	不支援
查詢 API Key 列表	支援	不支援
更新 / 停用 / 啟用 API Key	支援	不支援
存取其他租戶資料	支援	不支援

使用說明

使用 Master Key 呼叫既有 PrivAI API 時，系統將以管理者視角回傳跨租戶資料。
使用客戶 API Key 呼叫既有 PrivAI API 時，系統會自動套用該租戶的資料範圍限制（tenant scope）。
客戶 API Key 無需額外理解租戶概念，也不需改變既有 API 呼叫方式。

伺服器主機¶

測試 PrivAI 伺服器是否正常運作

curl -X 'GET' \
  'http://127.0.0.1:8000/v1/models' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your-api-key>'

Request Headers

Key	Value
Request Method	GET
accept	application/json
Authorization	Bearer

Response Body

{
  "object": "list",
  "data": [
    {
      "id": "ace-1-3b-reasoning",
      "object": "model",
      "created": 1677610602,
      "owned_by": "APMIC"
    }
    ...
  ]
}

API 列表¶

PrivAI 所有的 API 端點。

模型管理模組¶

請求方法	端點	描述
GET	/v1/models	取得所有模型

API Key 管理模組¶

請求方法	端點	描述
GET	/v1/api-keys	取得所有 API Key 列表
POST	/v1/api-keys	建立 API Key
PUT	/v1/api-keys/{id}	更新 / 停用 / 啟用 API Key

檔案管理模組¶

請求方法	端點	描述
GET	/v1/files	取得所有檔案列表
POST	/v1/files	上傳檔案
POST	/v1/files/{file_id}/parse	單一檔案轉換
GET	/v1/files/{file_id}	取得單一檔案資料
GET	/v1/files/{file_id}/content	下載檔案
DELETE	/v1/files/{file_id}	刪除單一檔案

知識版本管理模組¶

請求方法	端點	描述
GET	/v1/filesets	取得所有知識版本列表
POST	/v1/filesets	新增知識版本
GET	/v1/filesets/{fileset_id}	取得單一知識版本資料
GET	/v1/filesets/{fileset_id}/files	取得單一知識版本的檔案列表
PUT	/v1/filesets/{fileset_id}	更新知識版本
DELETE	/v1/filesets/{fileset_id}	刪除知識版本
POST	/v1/filesets/{fileset_id}/commit	commit 知識版本
DELETE	/v1/filesets/{fileset_id}/commit	取消 commit 知識版本
POST	/v1/filesets/{fileset_id}/duplicate	複製知識版本
POST	/v1/chat/references/{fileset_id}&{query}	資料參考搜尋 (在指定的知識版本中，搜尋相關的參考資料)

提示詞管理模組¶

請求方法	端點	描述
GET	/v1/prompts	取得所有提示詞列表
POST	/v1/prompts	新增提示詞
GET	/v1/prompts/{prompt_id}	取得單一提示詞資訊
DELETE	/v1/prompts/{prompt_id}	刪除提示詞
POST	/v1/prompts/{prompt_id}/optimize/auto	提示詞自動優化
POST	/v1/prompts/{prompt_id}/optimize/instruct	提示詞手動優化

對話模組¶

請求方法	端點	描述
POST	/v1/chat/completions	與 LLM 互動

其他工具¶

請求方法	端點	描述
POST	/v1/qa/generate	問答集生成