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

> Xác thực bằng khóa API bearer. Khóa thật và khóa thử nghiệm, kết quả trả về ở chế độ thử nghiệm, thu hồi khóa và đặt hạn mức chi tiêu hằng tháng cho từng khóa.

Nguồn: https://fileverity.com/vi/docs/authentication

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`.

**Yêu cầu đã xác thực: cURL**

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

**Yêu cầu đã xác thực: JavaScript**

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

**Yêu cầu đã xác thực: Python**

```python
import os
import 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ế độ.

|  | Khóa thật | Khóa thử nghiệm |
| --- | --- | --- |
| Tiền tố | `fv_live_...` | `fv_test_...` |
| Chạy các mô hình | Có | Không |
| Trừ vào số dư hoặc lượt dùng thử miễn phí | Có | Không bao giờ |
| Kết quả | Thật | Mẫu cố định |
| `livemode` trong phản hồi | `true` | `false` |
| Webhook | Được gửi | Không được gửi |

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.

**Lượt phát hiện văn bản mẫu, khóa thử nghiệm**

```json
{
  "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.

> **Lư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

| Mã lỗi | Trạng thái | Ý nghĩa |
| --- | --- | --- |
| `missing_api_key` | 401 | Không có header `Authorization: Bearer` nào được gửi. |
| `invalid_api_key` | 401 | Khóa sai định dạng, không tồn tại hoặc đã bị thu hồi. |
| `spend_limit_reached` | 402 | Khóa đã đạt hạn mức chi tiêu hằng tháng. |

Xem [Lỗi](https://fileverity.com/vi/docs/errors.md) để biết danh sách đầy đủ.