上傳檔案
上傳分三步:申請上傳位址、傳輸檔案、確認文件。上傳位址只能寫入一次,最長有效 1 小時。
1. 請求上傳位址
Section titled “1. 請求上傳位址”POST /api/v1/upload/presignX-API-Key: sk_your_keyContent-Type: application/json{ "filename": "report.docx", "file_size": 45678}| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
filename | 字串 | ✅ | 檔案名稱,伺服器端會根據副檔名來判斷檔案類型 |
file_size | 整數 | ✅ | 準確的位元組數,必須大於 0 |
mime_type | 字串 | — | 可省略,服務端不使用 |
回應:
{ "document_id": "4q8mx2q9z1k7p6ra", "upload_url": "https://upload.example/...", "upload_headers": { "Content-Type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "If-None-Match": "*" }, "finalize_token": "short_lived_token", "expires_in": 3600}2. 傳輸檔案
Section titled “2. 傳輸檔案”向 upload_url 發送 PUT,請求體為檔案原始位元組,並原樣發送 upload_headers 中的全部請求標頭。
# UPLOAD_URL、UPLOAD_CONTENT_TYPE 取自上一步响应的 upload_url 与 upload_headers["Content-Type"]curl --fail-with-body -X PUT "$UPLOAD_URL" \ -H "Content-Type: $UPLOAD_CONTENT_TYPE" \ -H "If-None-Match: *" \ --upload-file "report.docx"這一步不要攜帶 OmniDoc API Key。地址過期或傳輸失敗時重新申請。
3. 確認文件
Section titled “3. 確認文件”POST /api/v1/upload/finalizeX-API-Key: sk_your_keyContent-Type: application/json{"finalize_token":"short_lived_token"}成功後返回文件:
{ "document": { "id": "4q8mx2q9z1k7p6ra", "basename": "report.docx", "file_size": 45678, "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "created_at": "2026-10-01T12:00:00Z" }}確認成功後,文件才會進入檔案庫,才能用於建立任務。
filename 僅用於展示,請勿視為路徑或唯一標識。伺服器會替換非法字元,並為過長的名稱產生安全的下載名稱。
| 狀態 | 原因 |
|---|---|
400 | 檔案名或檔案大小無效,或上傳的大小與申請時不符 |
401 | 憑證或 finalize_token 無效、已過期 |
403 | finalize_token 不屬於目前帳號 |
410 | 未找到已上傳的檔案(傳輸未完成或位址已過期),請重新申請 |
413 | 超出單一檔案大小上限 |
415 | 檔案格式不支援,或檔案內容與副檔名不符 |
422 | Office 檔案已損壞或結構不安全 |
429 | 上傳過於頻繁 |
503 | 上傳服務暫時不可用,可稍後重試 |