Chuyển đến nội dung chính

Tài liệu API Fileverity

Tệp

Tải ảnh và tài liệu lên Fileverity: multipart cho tệp đến 4 MB, tải lên bằng URL ký trước cho tệp đến 50 MB. Đối tượng tệp, giới hạn và thời gian lưu giữ.

Xem dạng MarkdownCập nhật 2026-11-04

Ảnh và tài liệu được kiểm tra qua hai bước. Trước tiên bạn tải tệp lên bằng POST /files và nhận mã tệp. Sau đó bạn tạo một lượt phân tích tham chiếu đến mã đó. Văn bản không cần tệp; hãy dùng Phát hiện văn bản.

Tệp được hỗ trợ

Ảnh (fvimg-2)Tài liệu (fvdoc-3)
Định dạngjpeg, png, webppdf, docx, doc, rtf, odt, pptx, txt
Kích thước tối đa10 MB50 MB
Giới hạn khác40 megapixel100 trang

Hai cách tải lên

Phương thứcYêu cầuKích thướcTrạng thái tệp trong phản hồi
Multipartmultipart/form-data với trường fileTối đa 4 MBuploaded
URL ký trướcJSON với filename, content_type và bytes, sau đó PUT các byteTối đa 50 MBpending cho đến khi nhận được các byte

Ảnh bị giới hạn theo kích thước ảnh nêu ở trên, bất kể bạn dùng phương thức nào.

Tải lên bằng multipart

Gửi tệp đến 4 MB dưới dạng multipart/form-data trong trường file. Định dạng được nhận diện từ nội dung tệp, không phải từ tên hoặc kiểu được khai báo của tệp.

curl https://api.fileverity.com/v1/files \  -H "Authorization: Bearer $FILEVERITY_API_KEY" \  -F file=@claim-photo.jpg
{  "id": "file_8Hk2pQ4vN9sL1xR7cW3mY6zB",  "object": "file",  "filename": "claim-photo.jpg",  "bytes": 2481920,  "content_type": "image/jpeg",  "status": "uploaded",  "livemode": true,  "created": 1793700000,  "expires_at": 1793786400}

Tải lên bằng URL ký trước

Với tệp lớn hơn 4 MB, tối đa 50 MB, hãy yêu cầu một URL tải lên, rồi gửi các byte trực tiếp đến nơi lưu trữ.

  1. POST /files với nội dung JSON: filename (không bắt buộc), content_type và kích thước chính xác tính bằng bytes. Phản hồi có status: pending và một đối tượng upload.
  2. PUT các byte của tệp tới upload.url kèm các header trong upload.headers, trước thời điểm upload.expires_at. Yêu cầu này không cần header Authorization.
  3. Có thể truy vấn định kỳ GET /files/{id} cho đến khi status là uploaded.
  4. Tạo lượt phân tích với mã tệp.
FILE=$(curl -s https://api.fileverity.com/v1/files \  -H "Authorization: Bearer $FILEVERITY_API_KEY" \  -H "Content-Type: application/json" \  -d '{"filename": "contract.pdf", "content_type": "application/pdf", "bytes": 18874368}') UPLOAD_URL=$(echo "$FILE" | jq -r .upload.url)FILE_ID=$(echo "$FILE" | jq -r .id) curl -X PUT "$UPLOAD_URL" \  -H "content-type: application/pdf" \  --data-binary @contract.pdf
{  "id": "file_Pw3mY6zB8Hk2pQ4vN9sL1xR7",  "object": "file",  "filename": "contract.pdf",  "bytes": 18874368,  "content_type": "application/pdf",  "status": "pending",  "livemode": true,  "created": 1793700000,  "expires_at": 1793786400,  "upload": {    "url": "https://example.private.blob.vercel-storage.com/f/0d6f1c2e-7b1a-4c53-9a0e-5e8a41b3c7d2?signature=...",    "method": "PUT",    "headers": {      "content-type": "application/pdf"    },    "expires_at": 1793703600  }}

URL hiển thị ở đây đã được rút gọn. Hãy dùng nguyên URL trong phản hồi của bạn. Gửi header content-type đúng như giá trị trả về trong upload.headers.

Content type được chấp nhận

LoạiContent type
Ảnhimage/jpeg, image/png, image/webp
Tài liệuapplication/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/msword, application/rtf, application/vnd.oasis.opendocument.text, application/vnd.openxmlformats-officedocument.presentationml.presentation, text/plain

Đối tượng tệp

TrườngKiểuMô tả
idstringMã tệp, có tiền tố file_.
objectstringLuôn là file.
filenamestring hoặc nullTên tệp đã được làm sạch.
bytesinteger hoặc nullKích thước tính bằng byte.
content_typestringContent type được nhận diện hoặc được khai báo.
statusstringpending cho đến khi nhận đủ các byte được tải lên, sau đó là uploaded.
livemodebooleanfalse với các tệp được tạo bằng khóa thử nghiệm. Tệp được tách biệt theo chế độ.
createdintegerDấu thời gian Unix.
expires_atintegerDấu thời gian Unix mà sau đó tệp bị xóa.
uploadobjectChỉ có trong phản hồi cho yêu cầu tải lên dạng JSON: url, method (PUT), headers và expires_at.

Thời gian lưu giữ

  • Một tệp được lưu giữ tối đa 24 giờ (xem expires_at) rồi bị xóa.
  • Tệp bị xóa ngay khi một lượt phân tích bắt đầu từ tệp đó. Mỗi tệp đã tải lên chỉ dùng cho một lượt phân tích; hãy tải lên lại để kiểm tra lại.
  • DELETE /files/{id} xóa tệp và các byte đã lưu của tệp trước thời hạn.
  • Một không gian làm việc có thể cùng lúc chứa tối đa 50 tệp chưa hết hạn và 200 MB cho mỗi chế độ. Vượt quá mức đó, việc tải lên sẽ thất bại với pending_files_limit (HTTP 429, không có retry-after) cho đến khi các tệp được sử dụng, bị xóa hoặc hết hạn.
  • Mã tệp không tồn tại, đã hết hạn hoặc đã được sử dụng sẽ trả về file_not_found khi bạn tạo lượt phân tích, và not_found khi bạn lấy hoặc xóa tệp. file_not_found cũng được trả về khi quá trình tải lên upload.url chưa hoàn tất, vì vậy hãy chờ đến khi GET /files/{id} hiển thị uploaded.

Lỗi

Mã lỗiTrạng tháiNguyên nhân
missing_parameter400Không có trường file trong nội dung yêu cầu multipart.
unsupported_media_type415Nội dung yêu cầu không phải multipart/form-data cũng không phải JSON.
unsupported_file415Định dạng không được hỗ trợ.
invalid_file422Tệp trống, bị hỏng hoặc không đọc được.
file_too_large413Tệp multipart lớn hơn 4 MB, hoặc bytes vượt quá 50 MB.
invalid_parameter400Một trường JSON bị thiếu, sai kiểu hoặc không xác định.
invalid_json400Nội dung yêu cầu JSON không phải là một đối tượng.
pending_files_limit429Không gian làm việc có quá nhiều tệp tải lên chưa hết hạn. Phản hồi không kèm header retry-after.
idempotency_mismatch, idempotency_in_progress409Idempotency-Key đã được dùng với một yêu cầu khác, hoặc yêu cầu đầu tiên của khóa này vẫn đang chạy.

Khóa thử nghiệm kiểm tra tính hợp lệ của các lần tải lên nhưng không lưu các byte. Yêu cầu tải lên dạng JSON với khóa thử nghiệm trả về một đối tượng tải lên thử nghiệm (upload.test là true, tệp đã ở trạng thái uploaded): không có gì để PUT.