跳到內容

上傳檔案

上傳分三步:申請上傳位址、傳輸檔案、確認文件。上傳位址只能寫入一次,最長有效 1 小時。

POST /api/v1/upload/presign
X-API-Key: sk_your_key
Content-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
}

向 upload_url 發送 PUT,請求體為檔案原始位元組,並原樣發送 upload_headers 中的全部請求標頭。

Terminal window
# 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。地址過期或傳輸失敗時重新申請。

POST /api/v1/upload/finalize
X-API-Key: sk_your_key
Content-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 無效、已過期
403finalize_token 不屬於目前帳號
410未找到已上傳的檔案(傳輸未完成或位址已過期),請重新申請
413超出單一檔案大小上限
415檔案格式不支援,或檔案內容與副檔名不符
422Office 檔案已損壞或結構不安全
429上傳過於頻繁
503上傳服務暫時不可用,可稍後重試