# 單一檔案轉換

此 API 用於觸發指定檔案的文件解析流程，你可以透過 file_id 指定檔案，並設定 parsing_mode 與 webhook_url，讓系統開始進行文件轉換。

此 API 不直接回傳純文字內容；若需查詢解析狀態或取得解析結果，請改用其他查詢或下載相關 API。

```javascript
curl -X 'POST' \
  'http://127.0.0.1:8000/v1/files/{file_id}/parse' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "parsing_mode": "HQ",
    "webhook_url": "https://example.com/"
  }'
```

- 發出 parse 後，對應 parsing mode 的 parsing_state 會由 draft → queued / parsing → completed 或 failed

- 完成 parse 即為 completed

- parse state 僅表示該模式的文件解析結果，不代表該 file 是否已被某個 fileset commit 成知識庫

#### Request Headers

| **Key** | **Value** |
| --- | --- |
| Request Method | POST |
| accept | application/json |
| Authorization | Bearer &lt;your-api-key> |
| Content-Type | application/json |

#### Query Parameters

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

#### Request Payload

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

#### Response Body

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

#### Webhook Request Content

你可以透過 Webhook 用於接收此檔案轉換的結果。

#### Request Headers

| **Key** | **Value** |
| --- | --- |
| Request Method | POST |
| Content-Type | multipart/form-data |

#### Response Body

```javascript
{
  "object": "file",
  "id": "b0d1bdbc-4f94-40b0-9358-68c579c99e8c",
  "filename": "Atomic Habits: An Easy & Proven Way to Build Good Habits & Break Bad Ones.pdf",
  "filetype": "application/pdf",
  "bytes": 1463728,
  "metadata": {
    "source": "internal_policy",
    "language": "zh-Hant",
    "parsed_results": {
      "HQ": {
        "parsing_state": "completed",
        "character_count": 6789,
        "page_count": 8,
        "failed_page_numbers": []
      },
      "LQ": {
        "parsing_state": "draft",
        "character_count": null,
        "page_count": null,
        "failed_page_numbers": null
      }
    },
    "fail_detail": []
  },
  "purpose": "user_data",
  "created_at": "2025-01-01T00:00:14.173Z",
  "expires_at": null
}
```

**Field Explanation**

回傳「檔案物件」章節列表內容。
