# API 串接 & API 列表

### API 串接

#### 身份驗證

除另有註明的端點外，每一個 API 請求都必須包含有效的 API Key。請在 `Authorization` 標頭中以 Bearer 格式帶入：

```text
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 已過期（含被停用）、不存在或格式不正確時，系統會拒絕請求並回傳對應錯誤碼，詳見 [錯誤代碼說明-身份驗證類](https://privstation-docs.apmic.ai/latest/privai-400/錯誤代碼說明-身份驗證類.md)。

#### 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 伺服器是否正常運作：

```bash
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**

```json
{
  "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](https://privstation-docs.apmic.ai/latest/privai-400/建立-api-key.md) |
| GET | /v1/api-keys | 取得所有 API Key 列表 | [取得所有 API Key 列表](https://privstation-docs.apmic.ai/latest/privai-400/取得所有-api-key-列表.md) |
| PATCH | /v1/api-keys/{id} | 更新 ／ 停用 ／ 啟用 API Key | [更新 ／ 停用 ／ 啟用 API Key](https://privstation-docs.apmic.ai/latest/privai-400/更新-停用-啟用-api-key.md) |

#### Files（檔案管理）

| 請求方法 | 端點 | 描述 | 說明頁面 |
| --- | --- | --- | --- |
| GET | /v1/files | 取得所有檔案列表 | [取得所有檔案列表](https://privstation-docs.apmic.ai/latest/privai-400/取得所有檔案列表.md) |
| POST | /v1/files | 上傳檔案 | [上傳檔案](https://privstation-docs.apmic.ai/latest/privai-400/上傳檔案.md) |
| GET | /v1/files/{file_id} | 取得單一檔案資料 | [取得單一檔案資料](https://privstation-docs.apmic.ai/latest/privai-400/取得單一檔案資料.md) |
| DELETE | /v1/files/{file_id} | 刪除單一檔案 | [刪除單一檔案](https://privstation-docs.apmic.ai/latest/privai-400/刪除單一檔案.md) |
| POST | /v1/files/{file_id}/parse | 單一檔案轉換（解析） | [單一檔案轉換](https://privstation-docs.apmic.ai/latest/privai-400/單一檔案轉換.md) |
| GET | /v1/files/{file_id}/content | 下載檔案 | [下載檔案](https://privstation-docs.apmic.ai/latest/privai-400/下載檔案.md) |

#### Filesets（知識版本管理）

| 請求方法 | 端點 | 描述 | 說明頁面 |
| --- | --- | --- | --- |
| GET | /v1/filesets | 取得所有知識版本列表 | [取得所有知識版本列表](https://privstation-docs.apmic.ai/latest/privai-400/取得所有知識版本列表.md) |
| POST | /v1/filesets | 新增知識版本 | [新增知識版本](https://privstation-docs.apmic.ai/latest/privai-400/新增知識版本.md) |
| GET | /v1/filesets/{fileset_id} | 取得單一知識版本資料 | [取得單一知識版本資料](https://privstation-docs.apmic.ai/latest/privai-400/取得單一知識版本資料.md) |
| PUT | /v1/filesets/{fileset_id} | 更新知識版本 | [更新知識版本](https://privstation-docs.apmic.ai/latest/privai-400/更新知識版本.md) |
| DELETE | /v1/filesets/{fileset_id} | 刪除知識版本 | [刪除知識版本](https://privstation-docs.apmic.ai/latest/privai-400/刪除知識版本.md) |
| GET | /v1/filesets/{fileset_id}/files | 取得單一知識版本的檔案列表 | [取得單一知識版本的檔案列表](https://privstation-docs.apmic.ai/latest/privai-400/取得單一知識版本的檔案列表.md) |
| POST | /v1/filesets/{fileset_id}/commit | Commit 知識版本 | [Commit 知識版本](https://privstation-docs.apmic.ai/latest/privai-400/commit-知識版本.md) |
| DELETE | /v1/filesets/{fileset_id}/commit | 取消 Commit 知識版本 | [取消 Commit 知識版本](https://privstation-docs.apmic.ai/latest/privai-400/取消-commit-知識版本.md) |
| POST | /v1/filesets/{fileset_id}/duplicate | 複製知識版本 | [複製知識版本](https://privstation-docs.apmic.ai/latest/privai-400/複製知識版本.md) |

#### QA（問答集生成）

| 請求方法 | 端點 | 描述 | 說明頁面 |
| --- | --- | --- | --- |
| POST | /v1/qa/generate | 問答集生成 | [問答集生成](https://privstation-docs.apmic.ai/latest/privai-400/問答集生成.md) |

#### Prompts（提示詞管理）

| 請求方法 | 端點 | 描述 | 說明頁面 |
| --- | --- | --- | --- |
| GET | /v1/prompts | 取得所有提示詞列表 | [取得所有提示詞列表](https://privstation-docs.apmic.ai/latest/privai-400/取得所有提示詞列表.md) |
| POST | /v1/prompts | 新增提示詞 | [新增提示詞](https://privstation-docs.apmic.ai/latest/privai-400/新增提示詞.md) |
| GET | /v1/prompts/{prompt_id} | 取得單一提示詞資訊 | [取得單一提示詞資訊](https://privstation-docs.apmic.ai/latest/privai-400/取得單一提示詞資訊.md) |
| DELETE | /v1/prompts/{prompt_id} | 刪除提示詞 | [刪除提示詞](https://privstation-docs.apmic.ai/latest/privai-400/刪除提示詞.md) |
| POST | /v1/prompts/{prompt_id}/optimize/auto | 提示詞自動優化 | [提示詞自動優化](https://privstation-docs.apmic.ai/latest/privai-400/提示詞自動優化.md) |
| POST | /v1/prompts/{prompt_id}/optimize/instruct | 提示詞手動優化 | [提示詞手動優化](https://privstation-docs.apmic.ai/latest/privai-400/提示詞手動優化.md) |

#### Models（模型）

| 請求方法 | 端點 | 描述 | 說明頁面 |
| --- | --- | --- | --- |
| GET | /v1/models | 取得所有模型 | [取得所有模型](https://privstation-docs.apmic.ai/latest/privai-400/取得所有模型.md) |

#### Chat（對話）

| 請求方法 | 端點 | 描述 | 說明頁面 |
| --- | --- | --- | --- |
| POST | /v1/chat/completions | 與 LLM 互動 | [Chat Completions](https://privstation-docs.apmic.ai/latest/privai-400/chat-completions.md) |
| POST | /v1/chat/references?fileset_id={fileset_id}&query={query} | 資料參考搜尋（在指定的知識版本中搜尋相關的參考資料） | [資料參考搜尋](https://privstation-docs.apmic.ai/latest/privai-400/資料參考搜尋.md) |

#### MCP

| 請求方法 | 端點 | 描述 | 說明頁面 |
| --- | --- | --- | --- |
| POST | /v1/mcp/tools/discover | 探索指定外部 MCP server 提供的工具 | [探索 MCP 工具](https://privstation-docs.apmic.ai/latest/privai-400/探索-mcp-工具.md) |

#### Report Generation（報告生成，Beta）

:::warning[⚠️]

報告生成功能目前位於 `/beta` 路徑下，屬於實驗性、預覽性質的功能，未來可能變動（包含但不限於變更規格、移除功能），APMIC **不保證**其規格的向下相容性。

:::

| 請求方法 | 端點 | 描述 | 說明頁面 |
| --- | --- | --- | --- |
| POST | /beta/report-generation/templates | 建立報告模板，並觸發 PDF 模板解析流程 | [建立報告模板](https://privstation-docs.apmic.ai/latest/privai-400/建立報告模板.md) |
| GET | /beta/report-generation/templates/{template_id} | 取得報告模板目前狀態與資料 | [建立報告模板](https://privstation-docs.apmic.ai/latest/privai-400/建立報告模板.md) |
| PATCH | /beta/report-generation/templates/{template_id} | 更新已完成的報告模板內容 | [建立報告模板](https://privstation-docs.apmic.ai/latest/privai-400/建立報告模板.md) |
| POST | /beta/report-generation/templates/{template_id}/confirm | 確認模板 slot 結構，並觸發撰寫指引生成 | [建立報告模板](https://privstation-docs.apmic.ai/latest/privai-400/建立報告模板.md) |
| POST | /beta/report-generation/reports | 建立報告，並觸發章節草稿生成 | [報告生成](https://privstation-docs.apmic.ai/latest/privai-400/報告生成.md) |
| POST | /beta/report-generation/reports/{report_id}/confirm | 確認報告草稿，並觸發模板填充 | [報告生成](https://privstation-docs.apmic.ai/latest/privai-400/報告生成.md) |
| DELETE | /beta/report-generation/reports/{report_id} | 刪除報告 | [報告生成](https://privstation-docs.apmic.ai/latest/privai-400/報告生成.md) |
| GET | /beta/report-generation/reports/{report_id} | 取得報告目前狀態與資料 | [報告生成](https://privstation-docs.apmic.ai/latest/privai-400/報告生成.md) |
| POST | /beta/report-generation/reports/{report_id}/export | 將已完成的報告匯出為 PDF 檔案（回傳檔案物件） | [報告生成](https://privstation-docs.apmic.ai/latest/privai-400/報告生成.md) |
