跳至主要内容
版本:PrivStation 4.0.0
Markdown 原文

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

KeyValue
Request MethodGET
acceptapplication/json
AuthorizationBearer <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}/commitCommit 知識版本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 檔案(回傳檔案物件)報告生成