# 下載檔案

此 API 可取得指定檔案的完整處理結果，包含三個主要部分：

- **raw_file**：使用者上傳的原始檔案。

- **parsed_result**：系統解析後的文字內容，用於檢視與驗證原始語意。PrivAI 的解析結果是輸入檔案的文本轉譯，格式為 Markdown（可能含 HTML）。若需取得解析器輸出的原始結構（例如 PDF 的逐頁資訊），可加上 `output=json`。

- **chunks**：該檔案被切段後的段落清單（JSONL），每個段落可作為語意檢索或向量化的最小單位。

此 API 通常用於檢查內容處理狀況、人工審查段落是否正確，或手動建立 Fileset 前的資料確認流程。

```bash
curl -X 'GET' \
  'http://127.0.0.1:8000/v1/files/{file_id}/content?file_type=parsed_result&quality=HQ' \
  -H "Authorization: Bearer $PRIVAI_API_KEY" \
  -o parsed_result.md
```

#### Request Headers

| Key | Value |
| --- | --- |
| Request Method | GET |
| Authorization | `Bearer $PRIVAI_API_KEY` |

#### Path Parameters

| Field | Type | Note | Required |
| --- | --- | --- | --- |
| file_id | string | uuid | true |

#### Query Parameters

| Field | Type | Note | Required |
| --- | --- | --- | --- |
| file_type | string | 可選擇取得 `raw_file`、`parsed_result`、`chunks` 的結果 | false |
| quality | string | 僅對 `parsed_result`、`chunks` 有意義，可選 `HQ`、`LQ`、`STD`。PDF／圖片以 `HQ` 取得 HQ 解析結果、以 `LQ` 取得 FAST 解析結果；其他格式請使用 `STD` | false |
| output | string | 僅在 `file_type=parsed_result` 時有意義。設為 `json` 時，回應改為 JSON 格式 | false |

#### Response Body

未指定 `output=json` 時，回傳檔案內容（Binary，以附件形式下載，`Content-Disposition: attachment`）：

| file_type | Content-Type | 下載檔名 |
| --- | --- | --- |
| raw_file | 上傳時的 `filetype` | 原始檔名 |
| parsed_result | `text/markdown` | `{file_id}_parsed_result.md` |
| chunks | `application/jsonl` | `{file_id}_chunks.jsonl` |

若原始檔曾被系統自動判斷為 QA 題庫檔（`filetype` 為 `application/x-privai-qa`，詳見「上傳檔案」章節），下載 `raw_file` 時 Content-Type 會還原為標準 `.xlsx`（`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`）。  
**output=json**  
當 `file_type=parsed_result` 且 `output=json` 時，回傳 JSON（以下範例省略 `olmocr` 內的其餘欄位）：

```json
{
  "id": "b0d1bdbc-4f94-40b0-9358-68c579c99e8c",
  "filename": "company_policy.pdf",
  "filetype": "application/pdf",
  "used_quality": "HQ",
  "content": "# 公司政策\n\n第一章 ...",
  "olmocr": {
    "text": "# 公司政策\n\n第一章 ..."
  }
}
```

| Field | Detail |
| --- | --- |
| id | 檔案 ID |
| filename | 原始檔案名稱 |
| filetype | 檔案種類 |
| used_quality | 本次請求的 `quality` 值 |
| content | 解析後的文字內容（Markdown） |
| olmocr | 僅 PDF（及部分圖片）以 `quality=HQ` 下載時出現，為 HQ 解析器輸出的原始 JSON 結構（含 `text` 等欄位，實際欄位依解析器而定） |
| PyMuPDF | 僅 PDF 以 `quality=LQ` 下載時出現，為 FAST 解析器輸出的原始 JSON 結構 |

#### 常見錯誤代碼

| Error Code | HTTP Status | 情境 |
| --- | --- | --- |
| FILE_002 | 404 | 指定的檔案不存在 |
| FILE_007 | 404 | 指定品質的解析結果不存在（尚未解析或解析失敗），回應中帶 `quality` |
| FILE_008 | 404 | 指定品質的切段結果不存在，回應中帶 `quality` |
| — | 422 | `file_type` 或 `quality` 不是允許的值 |

身份驗證錯誤（`AUTH_001`～`AUTH_003`）詳見「錯誤代碼說明-身份驗證類」章節；檔案相關錯誤碼完整說明請參考 [錯誤代碼說明-檔案管理類](https://privstation-docs.apmic.ai/latest/privai-400/錯誤代碼說明-檔案管理類.md)。
