# 檔案物件

| **Field** | **Detail** |
| --- | --- |
| filename | 原始檔案名稱 |
| filetype | 檔案種類，包含 `application/pdf`、`image/png`、`image/jpeg`、`application/msword`、`application/vnd.openxmlformats-officedocument.wordprocessingml.document`、`text/html`、`text/plain`、`text/markdown`、`application/x-privai-qa` |
| bytes | 檔案大小 |
| purpose | (與 OpenAI 相容而保留) |
| id | 檔案的唯一鍵，UUID |
| object | 物件類型，固定為 `file` |
| metadata | 儲存與檔案相關的額外資訊 |
| metadata.parsed_results | 檔案在不同解析品質下的結果。系統會依實際支援與處理情況回傳對應品質的結果。**目前支援的解析品質有 ****`HQ`**** 與 ****`FAST`**。 |
| metadata.fail_detail | 保留檔案轉換的錯誤歷史 |
| metadata.parsed_results.[mode].parsing_state | 該解析品質下的轉換狀態，包含 draft、queued、parsing、completed、failed。其中 `[mode]` 目前僅可能為 `HQ` 或 `FAST`。 |
| metadata.parsed_results.[mode].character_count | 該解析品質下抽取出的字元數量 |
| metadata.parsed_results.[mode].page_count | 該解析品質下解析到的總頁數 |
| metadata.parsed_results.[mode].failed_page_numbers | 該解析品質下解析失敗的頁碼列表 |
| metadata.fail_detail | 保留檔案解析失敗的詳細資訊與錯誤歷史 |
| created_at | 檔案上傳、建立的時間 |
| expired_at | (與 OpenAI 相容而保留) |

**補充說明：**

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

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

1. used_quality 不會出現在 GET /v1/files 或 GET /v1/files/{file_id} 的 File 物件中。該欄位僅會出現在 Fileset File 物件，用來表示檔案在特定 Fileset commit 流程中實際採用的解析品質。
