Xác thực và khóa API

Mọi yêu cầu đều cần một khóa API, gửi dưới dạng bearer token trong header Authorization.

curl https://api.fileverity.com/v1/models \  -H "Authorization: Bearer $FILEVERITY_API_KEY"

const response = await fetch("https://api.fileverity.com/v1/models", {  headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY },});

import osimport requests requests.get("https://api.fileverity.com/v1/models", headers={"Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"]})

Khóa là thông tin bí mật. Hãy gọi API từ máy chủ của bạn, lưu khóa trong biến môi trường hoặc trình quản lý bí mật (secrets manager), và không bao giờ đưa khóa vào mã chạy trên trình duyệt hay ứng dụng di động.

Khóa thật và khóa thử nghiệm#

Khóa có dạng fv_live_ hoặc fv_test_ theo sau là 40 chữ cái và chữ số. Tiền tố quyết định chế độ.

Cả hai chế độ dùng chung một không gian làm việc. Chúng dùng cùng endpoint, cách kiểm tra tính hợp lệ, giới hạn tốc độ và mã lỗi, vì vậy bạn có thể xây dựng với khóa thử nghiệm rồi đổi khóa để chạy thật.

Hoạt động ở chế độ thử nghiệm#

• Phát hiện văn bản. Yêu cầu được kiểm tra tính hợp lệ như yêu cầu thật: vẫn áp dụng giới hạn độ dài tối thiểu, độ dài tối đa và việc kiểm tra ngôn ngữ. Phản hồi là một kết quả human cố định với score và ai_fraction bằng 0 và không có segments. usage được tính từ văn bản của bạn. Không có khoản nào bị tính phí hoặc được ghi lại.
• Tệp. Các lần tải lên được kiểm tra tính hợp lệ nhưng nội dung tệp không được lưu, và yêu cầu tải lên dạng JSON trả về một đối tượng tải lên thử nghiệm thay vì URL ký trước thật (upload.test là true), với tệp đã ở trạng thái uploaded. Tệp được tách biệt theo chế độ: khóa thử nghiệm không đọc được tệp thật, và khóa thật không đọc được tệp thử nghiệm.
• Tạo lượt phân tích. Trả về ngay 200 kèm status: succeeded, một mẫu cố định có mức L2 và hành động accept, cùng livemode: false. Mã phân tích bắt đầu bằng an_test và giống nhau với cùng một tệp. Mã báo cáo bắt đầu bằng FV-TEST- và không có trang xác minh công khai. Báo cáo mẫu chỉ chứa các trường có trong mẫu.
• Lấy một lượt phân tích. Chỉ hoạt động với mã phân tích mẫu. Liệt kê các lượt phân tích luôn trả về danh sách trống, hủy trả về not_cancelable, và không có PDF mẫu. Khóa thử nghiệm không đọc được các lượt phân tích thật hoặc PDF báo cáo thật.

{  "id": "tdet_Qm4vB7nP1sK8tL3wR6yZ2cXa",  "object": "text.detection",  "created": 1793664000,  "model": "fvdoc-3-text-2026-11-03",  "livemode": false,  "language": "en",  "verdict": "human",  "score": 0,  "ai_fraction": 0,  "segments": [],  "usage": {    "characters": 1412,    "free_characters": 0,    "billed_units": 2  }}

Tạo và thu hồi khóa#

Quản lý khóa trong Console, tại mục Khóa API.

• Tạo. Đặt tên cho khóa và chọn chế độ. Khóa đầy đủ chỉ hiển thị một lần. Fileverity chỉ lưu giá trị băm SHA-256 và bốn ký tự cuối, vì vậy khóa bị mất không thể khôi phục; hãy tạo khóa mới.
• Giới hạn. Một không gian làm việc có thể có tối đa 20 khóa đang hoạt động. Vượt quá mức này, việc tạo khóa sẽ thất bại với key_limit.
• Dùng lần cuối. Console hiển thị thời điểm mỗi khóa gửi yêu cầu gần nhất.
• Thu hồi. Các yêu cầu dùng khóa đã bị thu hồi sẽ thất bại ngay lập tức với invalid_api_key.
• Thành viên rời đi. Khi một thành viên rời khỏi không gian làm việc hoặc bị xóa, các khóa do họ tạo sẽ bị thu hồi. Hãy tạo khóa production bằng một tài khoản sẽ ở lại không gian làm việc.

Nếu khóa bị lộ#

1. Tạo một khóa mới.
2. Cập nhật phần mềm của bạn để dùng khóa đó.
3. Thu hồi khóa cũ.

Hạn mức chi tiêu hằng tháng#

Mỗi khóa có thể có hạn mức chi tiêu hằng tháng riêng, tính bằng số nguyên đô la Mỹ. Chỉ chủ sở hữu và quản trị viên không gian làm việc mới có thể đặt hoặc thay đổi hạn mức, khi tạo khóa hoặc sau đó bằng Sửa hạn mức. Khóa không có hạn mức chỉ bị giới hạn bởi số dư của bạn.

• Hạn mức tính theo số tiền khóa đã chi trong tháng dương lịch hiện tại (theo UTC) và được đặt lại vào ngày 1.
• Yêu cầu khiến khóa vượt hạn mức sẽ bị từ chối với spend_limit_reached (HTTP 402) trước khi bắt đầu xử lý, và không bị tính phí.
• Các lượt kiểm tra dùng thử miễn phí không mất phí và không được tính vào hạn mức. Các lượt kiểm tra thất bại hoặc bị hủy không bị tính phí và cũng không được tính vào hạn mức.
• Hạn mức áp dụng cho khóa thật. Khóa thử nghiệm không bao giờ phát sinh chi tiêu.

Hãy dùng một khóa riêng, với hạn mức riêng, cho từng dịch vụ hoặc môi trường. Khi đó, một tác vụ chạy mất kiểm soát cũng không thể chi vượt quá hạn mức của khóa đó.

Lỗi xác thực#

Xem Lỗi để biết danh sách đầy đủ.