# 單一檔案轉換

此 API 用於觸發指定檔案的文件解析流程，你可以透過 `file_id` 指定檔案，並設定 `parsing_mode` 與 `webhook_url`，讓系統開始進行文件轉換。  
此 API 為非同步處理，不直接回傳解析內容；若需查詢解析狀態或取得解析結果，請改用「取得單一檔案資料」或「下載檔案」API，或透過 Webhook 接收結果。

```bash
curl -X 'POST' \
  'http://127.0.0.1:8000/v1/files/{file_id}/parse' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $PRIVAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "parsing_mode": "HQ",
    "webhook_url": "https://example.com/webhook"
  }'
```

- 發出 parse 後，對應解析品質的 `parsing_state` 會由 `draft` → `queued` → `parsing` → `completed` 或 `failed`。

- `parsing_state` 僅表示該解析品質的文件解析結果，不代表該檔案是否已被某個 Fileset commit 成知識庫。

- 狀態說明詳見「File Parse State、Fileset File State 與 Fileset State 的差異」章節。

#### Request Headers

| Key | Value |
| --- | --- |
| Request Method | POST |
| accept | application/json |
| Authorization | `Bearer $PRIVAI_API_KEY` |
| Content-Type | application/json |

#### Path Parameters

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

#### Request Payload

```json
{
  "parsing_mode": "HQ",
  "webhook_url": "https://example.com/webhook"
}
```

**Field Explanation**

| Field | Type | Detail | Required |
| --- | --- | --- | --- |
| parsing_mode | string | 解析模式，可用值：`HQ`、`FAST` | true |
| webhook_url | string (url) | 解析結束（成功或失敗）時，系統會以 POST 通知此 URL | false |

:::warning[⚠️]

`parsing_mode` 只接受 `HQ` 與 `FAST`（**不是** `LQ`）。`LQ`／`STD` 是解析結果的品質標記，用於「下載檔案」API 的 `quality` 參數與 `metadata.parsed_results` 的 key，兩者不可混用。

:::

解析模式與結果品質的對應：

| 檔案類型 | parsing_mode = HQ | parsing_mode = FAST |
| --- | --- | --- |
| PDF、圖片 | 結果寫入 `parsed_results.HQ` | 結果寫入 `parsed_results.LQ` |
| 其他格式（Word、純文字、Markdown、HTML、試算表、CSV、QA 題庫檔） | 結果寫入 `parsed_results.STD` | 沒有 FAST 模式，等同 HQ，結果寫入 `parsed_results.STD` |

PDF、圖片以 HQ 解析失敗時，系統可能自動改以 FAST 解析，此時 `parsed_results.HQ.parsing_state` 會是 `failed`（失敗原因記錄在 `metadata.fail_detail`），結果則寫入 `parsed_results.LQ`。解析模式的選擇建議詳見「分頁策略 ＆ 文件解析模式優化策略 (PDF)」章節。

#### Response Body

```json
{
  "detail": "Start parsing file b0d1bdbc-4f94-40b0-9358-68c579c99e8c with HQ"
}
```

若同一個檔案以相同解析模式正在解析中，不會重複啟動，回應為：

```json
{
  "detail": "File b0d1bdbc-4f94-40b0-9358-68c579c99e8c is already being parsed"
}
```

#### Webhook Request Content

若有帶 `webhook_url`，解析結束（成功或失敗）時系統會發送通知。Webhook 發送失敗不會影響解析結果，系統也不會重試。  
**Request Headers**

| Key | Value |
| --- | --- |
| Request Method | POST |
| Content-Type | application/json |

**Request Body**  
內容為解析結束當下的檔案資訊。解析成功時 `object` 為 `fileset.file`，並帶 `used_quality`（實際採用的解析品質，`HQ`／`LQ`／`STD`）；解析失敗時 `object` 為 `file`，可從 `metadata.fail_detail` 查看失敗原因。

```json
{
  "object": "fileset.file",
  "id": "b0d1bdbc-4f94-40b0-9358-68c579c99e8c",
  "filename": "company_policy.pdf",
  "filetype": "application/pdf",
  "bytes_": 1463728,
  "metadata": {
    "parsed_results": {
      "HQ": {
        "parsing_state": "completed",
        "character_count": 6789,
        "page_count": 8,
        "failed_page_numbers": []
      },
      "LQ": {
        "parsing_state": "draft"
      }
    },
    "fail_detail": [],
    "source": "internal_policy",
    "language": "zh-Hant"
  },
  "state": null,
  "used_quality": "HQ",
  "purpose": "user_data",
  "created_at": "2025-01-01T00:00:14.173000Z",
  "expires_at": null
}
```

備註：Webhook 內容中檔案大小的 key 為 `bytes_`（與 API 回應的 `bytes` 不同）。其餘欄位說明請參考「[檔案物件](https://privstation-docs.apmic.ai/latest/privai-400/檔案物件.md)」。

#### 常見錯誤代碼

| Error Code | HTTP Status | 情境 |
| --- | --- | --- |
| FILE_002 | 404 | 指定的檔案不存在 |
| — | 422 | 缺少 `parsing_mode`，或值不是 `HQ`／`FAST`；`webhook_url` 不是合法 URL |

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