API 串接 & API 列表
API 串接
身份驗證
除另有註明的端點外,每一個 API 請求都必須包含有效的 API Key。請在 Authorization 標頭中以 Bearer 格式帶入:
Authorization: Bearer <your-api-key>
PrivAI 支援兩種類型的 API Key:
-
Master Key:具有管理者權限,可跨租戶檢視與管理資料,也是唯一可以呼叫 API Key 管理相關 API 的金鑰。
-
租戶 Key(Tenant Key):提供給單一客戶或單一租戶使用,只能存取該 API Key 所屬租戶的資料。
備註:
-
Master Key 由部署管理者設定並保管。
-
租戶 Key 透過「建立 API Key」API 取得,租戶 Key 以
sk-開頭。 -
租戶 Key 的呼叫方式與 Master Key 完全相同,只需將金鑰替換為客戶專屬的 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 時,系統以管理者視角回傳跨租戶資料。
-
使用租戶 Key 呼叫 PrivAI API 時,系統會自動套用該租戶的資料範圍限制(Tenant Scope),詳見「Tenant Scope 與資料隔離」章節。
-
租戶 Key 的使用者無需額外理解租戶概念,也不需改變 API 呼叫方式。
伺服器主機
可呼叫「取得所有模型」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 <your-api-key> |
Response Body
{
"object": "list",
"data": [
{
"id": "ace-1",
"object": "model",
"created": 1677610602,
"owned_by": "N/A",
"max_input_characters": 128000
}
]
}
回應欄位說明詳見「取得所有模型」章節。
API 列表
以下為 PrivAI 4.0.0 對外提供的所有 API 端點,分組名稱與順序與 API 文件(Swagger)一致。點選「說明頁面」可前往該端點的詳細說明。
API Keys(API Key 管理)
僅 Master Key 可呼叫。
| 請求方法 | 端點 | 描述 | 說明頁面 |
|---|---|---|---|
| POST | /v1/api-keys | 建立 API Key | 建立 API Key |
| GET | /v1/api-keys | 取得所有 API Key 列表 | 取得所有 API Key 列表 |
| PATCH | /v1/api-keys/{id} | 更新 / 停用 / 啟用 API Key | 更新 / 停用 / 啟用 API Key |
Files(檔案管理)
| 請求方法 | 端點 | 描述 | 說明頁面 |
|---|---|---|---|
| GET | /v1/files | 取得所有檔案列表 | 取得所有檔案列表 |
| POST | /v1/files | 上傳檔案 | 上傳檔案 |
| GET | /v1/files/{file_id} | 取得單一檔案資料 | 取得單一檔案資料 |
| DELETE | /v1/files/{file_id} | 刪除單一檔案 | 刪除單一檔案 |
| POST | /v1/files/{file_id}/parse | 單一檔案轉換(解析) | 單一檔案轉換 |
| GET | /v1/files/{file_id}/content | 下載檔案 | 下載檔案 |
Filesets(知識版本管理)
| 請求方法 | 端點 | 描述 | 說明頁面 |
|---|---|---|---|
| GET | /v1/filesets | 取得所有知識版本列表 | 取得所有知識版本列表 |
| POST | /v1/filesets | 新增知識版本 | 新增知識版本 |
| GET | /v1/filesets/{fileset_id} | 取得單一知識版本資料 | 取得單一知識版本資料 |
| PUT | /v1/filesets/{fileset_id} | 更新知識版本 | 更新知識版本 |
| DELETE | /v1/filesets/{fileset_id} | 刪除知識版本 | 刪除知識版本 |
| GET | /v1/filesets/{fileset_id}/files | 取得單一知識版本的檔案列表 | 取得單一知識版本的檔案列表 |
| POST | /v1/filesets/{fileset_id}/commit | Commit 知識版本 | Commit 知識版本 |
| DELETE | /v1/filesets/{fileset_id}/commit | 取消 Commit 知識版本 | 取消 Commit 知識版本 |
| POST | /v1/filesets/{fileset_id}/duplicate | 複製知識版本 | 複製知識版本 |
QA(問答集生成)
| 請求方法 | 端點 | 描述 | 說明頁面 |
|---|---|---|---|
| POST | /v1/qa/generate | 問答集生成 | 問答集生成 |
Prompts(提示詞管理)
| 請求方法 | 端點 | 描述 | 說明頁面 |
|---|---|---|---|
| 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 | 提示詞手動優化 | 提示詞手動優化 |
Models(模型)
| 請求方法 | 端點 | 描述 | 說明頁面 |
|---|---|---|---|
| GET | /v1/models | 取得所有模型 | 取得所有模型 |
Chat(對話)
| 請求方法 | 端點 | 描述 | 說明頁面 |
|---|---|---|---|
| POST | /v1/chat/completions | 與 LLM 互動 | Chat Completions |
| POST | /v1/chat/references?fileset_id={fileset_id}&query={query} | 資料參考搜尋(在指定的知識版本中搜尋相關的參考資料) | 資料參考搜尋 |
MCP
| 請求方法 | 端點 | 描述 | 說明頁面 |
|---|---|---|---|
| POST | /v1/mcp/tools/discover | 探索指定外部 MCP server 提供的工具 | 探索 MCP 工具 |
Report Generation(報告生成,Beta)
報告生成功能目前位於 /beta 路徑下,屬於實驗性、預覽性質的功能,未來可能變動(包含但不限於變更規格、移除功能),APMIC 不保證其規格的向下相容性。
| 請求方法 | 端點 | 描述 | 說明頁面 |
|---|---|---|---|
| POST | /beta/report-generation/templates | 建立報告模板,並觸發 PDF 模板解析流程 | 建立報告模板 |
| GET | /beta/report-generation/templates/{template_id} | 取得報告模板目前狀態與資料 | 建立報告模板 |
| PATCH | /beta/report-generation/templates/{template_id} | 更新已完成的報告模板內容 | 建立報告模板 |
| POST | /beta/report-generation/templates/{template_id}/confirm | 確認模板 slot 結構,並觸發撰寫指引生成 | 建立報告模板 |
| POST | /beta/report-generation/reports | 建立報告,並觸發章節草稿生成 | 報告生成 |
| POST | /beta/report-generation/reports/{report_id}/confirm | 確認報告草稿,並觸發模板填充 | 報告生成 |
| DELETE | /beta/report-generation/reports/{report_id} | 刪除報告 | 報告生成 |
| GET | /beta/report-generation/reports/{report_id} | 取得報告目前狀態與資料 | 報告生成 |
| POST | /beta/report-generation/reports/{report_id}/export | 將已完成的報告匯出為 PDF 檔案(回傳檔案物件) | 報告生成 |