跳至主要内容
版本:PrivStation 4.0.0
Markdown 原文

單一檔案轉換

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

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​

KeyValue
Request MethodPOST
acceptapplication/json
AuthorizationBearer $PRIVAI_API_KEY
Content-Typeapplication/json

Path Parameters​

FieldTypeNoteRequired
file_idstringuuidtrue

Request Payload​

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

Field Explanation

FieldTypeDetailRequired
parsing_modestring解析模式,可用值:HQ、FASTtrue
webhook_urlstring (url)解析結束(成功或失敗)時,系統會以 POST 通知此 URLfalse
⚠️

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

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

檔案類型parsing_mode = HQparsing_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​

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

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

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

Webhook Request Content​

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

KeyValue
Request MethodPOST
Content-Typeapplication/json

Request Body
內容為解析結束當下的檔案資訊。解析成功時 object 為 fileset.file,並帶 used_quality(實際採用的解析品質,HQ/LQ/STD);解析失敗時 object 為 file,可從 metadata.fail_detail 查看失敗原因。

{
"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 不同)。其餘欄位說明請參考「檔案物件」。

常見錯誤代碼​

Error CodeHTTP Status情境
FILE_002404指定的檔案不存在
—422缺少 parsing_mode,或值不是 HQ/FAST;webhook_url 不是合法 URL

身份驗證錯誤(AUTH_001~AUTH_003)詳見「錯誤代碼說明-身份驗證類」章節;檔案相關錯誤碼完整說明請參考 錯誤代碼說明-檔案管理類。