下載檔案
此 API 可取得指定檔案的完整處理結果,包含三個主要部分:
-
raw_file:使用者上傳的原始檔案。
-
parsed_result:系統解析後的文字內容,用於檢視與驗證原始語意。PrivAI 的解析結果是輸入檔案的文本轉譯,格式為 Markdown(可能含 HTML)。若需取得解析器輸出的原始結構(例如 PDF 的逐頁資訊),可加上
output=json。 -
chunks:該檔案被切段後的段落清單(JSONL),每個段落可作為語意檢索或向量化的最小單位。
此 API 通常用於檢查內容處理狀況、人工審查段落是否正確,或手動建立 Fileset 前的資料確認流程。
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 內的其餘欄位):
{
"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)詳見「錯誤代碼說明-身份驗證類」章節;檔案相關錯誤碼完整說明請參考 錯誤代碼說明-檔案管理類。