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ờ.
1. Yêu cầu địa chỉ tải lên
Phần tiêu đề “1. Yêu cầu địa chỉ tải lên”POST /api/v1/upload/presignX-API-Key: sk_your_keyContent-Type: application/json{ "filename": "report.docx", "file_size": 45678}| Trường | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
filename | chuỗ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_size | số nguyên | ✅ | Kích thước chính xác tính bằng byte, lớn hơn 0 |
mime_type | chuỗ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}2. Gửi tệp
Phần tiêu đề “2. Gửi tệp”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.
# UPLOAD_URL and UPLOAD_CONTENT_TYPE come from upload_url and upload_headers["Content-Type"] in the previous responsecurl --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.
3. Xác nhận tài liệu
Phần tiêu đề “3. Xác nhận tài liệu”POST /api/v1/upload/finalizeX-API-Key: sk_your_keyContent-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.
Tên tệp
Phần tiêu đề “Tên tệp”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ái | Nguyên nhân |
|---|---|
400 | Tê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 |
401 | Tín chỉ hoặc finalize_token không hợp lệ hoặc đã hết hạn |
403 | finalize_token thuộc về một tài khoản khác |
410 | Khô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 |
413 | Vượ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 |
422 | Tệp Office bị hỏng hoặc không đảm bảo an toàn về mặt cấu trúc |
429 | Quá nhiều lượt tải lên |
503 | Dịch vụ tải lên tạm thời không khả dụng; vui lòng thử lại sau |