# 檔案物件

| Field | Detail |
| --- | --- |
| object | 物件類型，固定為 `file` |
| id | 檔案的唯一鍵，UUID |
| filename | 原始檔案名稱 |
| filetype | 檔案種類（MIME type），包含 `application/pdf`、`image/png`、`image/jpeg`、`application/msword`、`application/vnd.openxmlformats-officedocument.wordprocessingml.document`、`text/html`、`text/plain`、`text/markdown`、`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`、`application/vnd.ms-excel`、`application/vnd.oasis.opendocument.spreadsheet`、`application/vnd.ms-excel.sheet.binary.macroenabled.12`、`text/csv`，以及 QA 題庫檔的內部型別 `application/x-privai-qa` |
| bytes | 檔案大小（bytes） |
| metadata | 儲存與檔案相關的額外資訊，包含系統欄位 `parsed_results`、`fail_detail`，以及上傳時使用者自訂的欄位 |
| `metadata.parsed_results` | 檔案在不同解析品質下的結果。PDF／圖片類檔案會有 `HQ` 與 `LQ` 兩組結果；其餘檔案類型（Word、HTML、純文字、Markdown、試算表、CSV、QA 題庫檔）僅有單一 `STD` 結果。`FAST` 是觸發解析時 `parsing_mode` 參數的值，不會出現在 `parsed_results` 的 key 中 |
| `metadata.parsed_results.[mode].parsing_state` | 該解析品質下的轉換狀態，包含 `draft`、`queued`、`parsing`、`completed`、`failed`。其中 `[mode]` 為 `HQ`、`LQ` 或 `STD` |
| `metadata.parsed_results.[mode].character_count` | 該解析品質下抽取出的字元數量 |
| `metadata.parsed_results.[mode].page_count` | 該解析品質下解析到的總頁數（僅 `HQ`／`LQ`） |
| `metadata.parsed_results.[mode].failed_page_numbers` | 該解析品質下解析失敗的頁碼列表（僅 `HQ`／`LQ`） |
| `metadata.fail_detail` | 檔案解析失敗的錯誤歷史（陣列，最新的在最前面）。每筆包含 `timestamp`、`error_type`、`error_message`，並可能包含 `reason`、`step`、`extra` |
| purpose | (與 OpenAI 相容而保留) |
| created_at | 檔案上傳、建立的時間 |
| expires_at | (與 OpenAI 相容而保留) |

**補充說明：**

1. File 物件本身不使用單一 `state` 欄位表示整體狀態。若需判斷檔案解析進度，請查看 `metadata.parsed_results` 中各解析品質對應的 `parsing_state`。

1. 同一個檔案可能在不同解析品質下有不同結果，應分別查看各品質狀態，而非以單一欄位統一表示。

1. `parsing_state` 為 `draft` 時，該解析品質只會回傳 `parsing_state`，不含 `character_count` 等欄位。

1. `GET /v1/files` 與 `GET /v1/files/{file_id}` 會省略值為 null 的欄位，因此這兩個 API 的回應中不會出現 `expires_at`。

1. `used_quality` 不會出現在 `GET /v1/files` 或 `GET /v1/files/{file_id}` 的 File 物件中。該欄位僅會出現在 Fileset File 物件（見 [取得單一知識版本的檔案列表](https://privstation-docs.apmic.ai/latest/privai-400/取得單一知識版本的檔案列表.md)），用來表示檔案在特定 Fileset commit 流程中實際採用的解析品質。
