Bỏ qua để đến nội dung

Tải tệp lên

Việc tải lên gồm ba bước: yêu cầu địa chỉ tải lên, gửi tệp và xác nhận tài liệu. Một địa chỉ tải lên chỉ có thể được tạo một lần và có hiệu lực tối đa 1 giờ.

POST /api/v1/upload/presign
X-API-Key: sk_your_key
Content-Type: application/json
{
"filename": "report.docx",
"file_size": 45678
}
TrườngLoạiBắt buộcMô tả
filenamechuỗi✅Tên tệp; máy chủ xác định loại tệp dựa trên phần mở rộng
file_sizesố nguyên✅Kích thước chính xác tính bằng byte, lớn hơn 0
mime_typechuỗi—Tùy chọn; máy chủ không sử dụng

Phản hồi:

{
"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
}

Gửi một PUT đến upload_url với nội dung là các byte của tệp thô, và gửi từng tiêu đề trong upload_headers chính xác như được cung cấp.

Terminal window
# UPLOAD_URL and UPLOAD_CONTENT_TYPE come from upload_url and upload_headers["Content-Type"] in the previous response
curl --fail-with-body -X PUT "$UPLOAD_URL" \
-H "Content-Type: $UPLOAD_CONTENT_TYPE" \
-H "If-None-Match: *" \
--upload-file "report.docx"

Không gửi khóa API OmniDoc của bạn ở bước này. Nếu địa chỉ hết hạn hoặc chuyển khoản thất bại, hãy yêu cầu một địa chỉ mới.

POST /api/v1/upload/finalize
X-API-Key: sk_your_key
Content-Type: application/json
{"finalize_token":"short_lived_token"}

Nếu thành công, tài liệu sẽ được trả về:

{
"document": {
"id": "4q8mx2q9z1k7p6ra",
"basename": "report.docx",
"file_size": 45678,
"mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"created_at": "2026-10-01T12:00:00Z"
}
}

Chỉ sau khi được xác nhận, tài liệu mới được đưa vào thư viện tệp và có thể sử dụng cho các công việc.

filename chỉ dùng để hiển thị; không được sử dụng làm đường dẫn hoặc định danh duy nhất. Máy chủ sẽ thay thế các ký tự không hợp lệ và tạo tên tải xuống an toàn cho những tên quá dài.

Trạng tháiNguyên nhân
400Tên tệp hoặc kích thước không hợp lệ, hoặc kích thước đã tải lên khác với yêu cầu
401Tín chỉ hoặc finalize_token không hợp lệ hoặc đã hết hạn
403finalize_token thuộc về một tài khoản khác
410Không tìm thấy tệp đã tải lên (quá trình truyền chưa hoàn tất hoặc địa chỉ đã hết hạn); vui lòng yêu cầu một địa chỉ mới
413Vượt quá giới hạn kích thước mỗi tệp
415Định dạng không được hỗ trợ, hoặc nội dung không khớp với phần mở rộng
422Tệp Office bị hỏng hoặc không đảm bảo an toàn về mặt cấu trúc
429Quá nhiều lượt tải lên
503Dịch vụ tải lên tạm thời không khả dụng; vui lòng thử lại sau