# Bắt đầu nhanh

> Tạo không gian làm việc, tạo khóa API và chạy các lượt kiểm tra văn bản và ảnh đầu tiên bằng cURL, JavaScript fetch hoặc Python requests.

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

Trang này hướng dẫn bạn từ bước đăng ký đến kết quả đầu tiên. Bạn cần một tài khoản Fileverity, một terminal có curl và jq, và một tệp JPEG, PNG hoặc WebP cho ví dụ về ảnh.

## 1. Mở Console

Đăng nhập tại [fileverity.com/console](https://fileverity.com/console?lang=vi) bằng mã gửi qua email hoặc Google. Lần đăng nhập đầu tiên sẽ tạo một không gian làm việc cá nhân với số dư trả trước riêng.

Không gian làm việc đầu tiên của bạn có sẵn 5 lượt kiểm tra ảnh hoặc tài liệu miễn phí và 5.000 ký tự văn bản miễn phí. Không cần thẻ. Mỗi người chỉ có một lượt dùng thử miễn phí, và số lượt cho mỗi tên miền email công ty có giới hạn. Đồng nghiệp nên tham gia qua lời mời. Lượt dùng thử miễn phí được dùng trước số dư của bạn. Xem [Giá và thanh toán](https://fileverity.com/vi/docs/pricing.md#free-start).

## 2. Tạo khóa API

Mở **Khóa API**, chọn **Tạo khóa**, đặt tên cho khóa và chọn chế độ. Hãy tạo khóa **Thử nghiệm** trước: khóa này trả về kết quả mẫu cố định, không bao giờ gọi mô hình và không bao giờ bị tính phí. Khóa đầy đủ chỉ hiển thị một lần, vì vậy hãy sao chép ngay bây giờ.

Không đưa khóa vào kho mã nguồn hoặc mã chạy trên trình duyệt. Hãy xuất khóa thành biến môi trường:

**Môi trường: Shell**

```bash
export FILEVERITY_API_KEY=fv_test_...
```

## 3. Xác minh khóa của bạn

`GET /models` hoạt động với mọi khóa hợp lệ và không bao giờ bị tính phí. Phản hồi `200` liệt kê các mô hình cho biết khóa dùng được. Phản hồi `401` nghĩa là khóa bị thiếu, gõ sai hoặc đã bị thu hồi.

**Xác minh khóa của bạn: cURL**

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

**Xác minh khóa của bạn: JavaScript**

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

**Xác minh khóa của bạn: Python**

```python
import os
import requests

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

## 4. Kiểm tra một đoạn văn bản

Gửi văn bản thuần túy có ít nhất 100 từ tới `POST /text/detections`. Các ví dụ đọc văn bản từ một tệp, vì vậy trước tiên hãy lưu một đoạn văn bất kỳ có từ 100 từ trở lên thành `essay.txt`. Lệnh này ghi ra một văn bản mẫu:

**Ghi essay.txt**

```bash
cat > essay.txt <<'EOF'
Honestly, the delivery was a mess. The driver turned up at six in the evening,
the pallet was wet on one side, and nobody at the depot would pick up the
phone until Monday. I photographed everything before signing, which is the
only reason we have a leg to stand on. In today's fast-paced logistics
landscape, it is essential for businesses to prioritize reliable delivery
performance, as timely and undamaged shipments play a pivotal role in
fostering customer trust and long-term satisfaction. We lost two days. Marta
rebuilt the schedule by hand and the Leeds order still went out late. Moving
forward, it is crucial to implement robust quality assurance measures and
establish clear communication channels, ensuring that all stakeholders remain
aligned and that potential issues are proactively addressed. For now I am
asking for a credit note and a named contact. Not another apology.
EOF
```

**Lượt kiểm tra văn bản đầu tiên: cURL**

```bash
curl https://api.fileverity.com/v1/text/detections \
  -H "Authorization: Bearer $FILEVERITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -Rs '{text: .}' essay.txt)"
```

**Lượt kiểm tra văn bản đầu tiên: JavaScript**

```javascript
import { readFile } from "node:fs/promises";

const response = await fetch("https://api.fileverity.com/v1/text/detections", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.FILEVERITY_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ text: await readFile("essay.txt", "utf8") }),
});
const detection = await response.json();
if (!response.ok) throw new Error(detection.error.code + ": " + detection.error.message);
console.log(detection.verdict, detection.ai_fraction);
```

**Lượt kiểm tra văn bản đầu tiên: Python**

```python
import os
import requests

response = requests.post(
    "https://api.fileverity.com/v1/text/detections",
    headers={"Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"]},
    json={"text": open("essay.txt", encoding="utf-8").read()},
)
detection = response.json()
if not response.ok:
    raise RuntimeError(detection["error"]["code"] + ": " + detection["error"]["message"])
print(detection["verdict"], detection["ai_fraction"])
```

Với khóa thử nghiệm, phản hồi là một kết quả cố định cho văn bản do người viết. Với khóa thật, phản hồi trông như sau:

**Phản hồi, khóa thật**

```json
{
  "id": "tdet_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "text.detection",
  "created": 1793664000,
  "model": "fvdoc-3-text-2026-11-03",
  "livemode": true,
  "language": "en",
  "verdict": "mixed",
  "score": 0.97,
  "ai_fraction": 0.41,
  "segments": [
    {
      "start": 212,
      "end": 433,
      "score": 0.97
    },
    {
      "start": 579,
      "end": 790,
      "score": 0.93
    }
  ],
  "usage": {
    "characters": 1412,
    "free_characters": 0,
    "billed_units": 2
  }
}
```

Chi tiết, kể cả cách hoạt động của offset, có trong [Phát hiện văn bản](https://fileverity.com/vi/docs/text-detections.md).

## 5. Kiểm tra một ảnh

Ảnh và tài liệu cần hai lệnh gọi: tải tệp lên, rồi tạo một lượt phân tích tham chiếu đến tệp đó. Một lượt phân tích là một lượt kiểm tra ảnh hoặc tài liệu. `Prefer: wait=60` giữ yêu cầu cho đến khi có kết quả, tối đa 60 giây.

**Lượt kiểm tra ảnh đầu tiên: cURL**

```bash
FILE_ID=$(curl -s https://api.fileverity.com/v1/files \
  -H "Authorization: Bearer $FILEVERITY_API_KEY" \
  -F file=@photo.jpg | jq -r .id)

curl https://api.fileverity.com/v1/analyses \
  -H "Authorization: Bearer $FILEVERITY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=60" \
  -d "{\"model\": \"fvimg-2\", \"file\": \"$FILE_ID\"}"
```

**Lượt kiểm tra ảnh đầu tiên: JavaScript**

```javascript
import { readFile } from "node:fs/promises";

const headers = { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY };

const form = new FormData();
form.append("file", new Blob([await readFile("photo.jpg")], { type: "image/jpeg" }), "photo.jpg");
const file = await (await fetch("https://api.fileverity.com/v1/files", { method: "POST", headers, body: form })).json();

const response = await fetch("https://api.fileverity.com/v1/analyses", {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json", Prefer: "wait=60" },
  body: JSON.stringify({ model: "fvimg-2", file: file.id }),
});
const analysis = await response.json();
console.log(analysis.status, analysis.summary, analysis.report_url);
```

**Lượt kiểm tra ảnh đầu tiên: Python**

```python
import os
import requests

headers = {"Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"]}

file = requests.post("https://api.fileverity.com/v1/files", headers=headers, files={"file": open("photo.jpg", "rb")}).json()

response = requests.post(
    "https://api.fileverity.com/v1/analyses",
    headers={**headers, "Prefer": "wait=60"},
    json={"model": "fvimg-2", "file": file["id"]},
)
analysis = response.json()
print(analysis["status"], analysis["summary"], analysis["report_url"])
```

Một lượt phân tích đã hoàn tất trả về `200` kèm `status: succeeded`, một `summary` ngắn và `result.report` đầy đủ. Nếu hết thời gian chờ trước đó, bạn nhận được `202` kèm `status: processing`; hãy lấy kết quả sau bằng `GET /analyses/{id}` hoặc nhận webhook. Xem [Lượt phân tích](https://fileverity.com/vi/docs/analyses.md).

**Phản hồi, khóa thật**

```json
{
  "id": "an_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "analysis",
  "created": 1793700120,
  "model": "fvimg-2-2026-10-30",
  "livemode": true,
  "status": "succeeded",
  "file": {
    "name": "claim-photo.jpg",
    "bytes": 2481920,
    "format": "jpeg"
  },
  "report_id": "FV-7K2M-9QXD-4T8R",
  "report_url": "https://fileverity.com/verify/FV-7K2M-9QXD-4T8R",
  "summary": {
    "level": "L2",
    "assessment": "authentic_untouched",
    "action": "accept",
    "ai": "very_low",
    "edit": "none"
  },
  "result": {
    "report": {
      "schema": "fileverity.report/1",
      "id": "FV-7K2M-9QXD-4T8R"
    },
    "stamped_at": 1793700130
  },
  "error": null,
  "progress": null,
  "usage": {
    "amount": 199,
    "currency": "usd",
    "funding": "balance"
  },
  "metadata": {
    "order_id": "A-10492"
  },
  "completed_at": 1793700131,
  "expires_at": 1794304931
}
```

> **Lưu ý.** Với khóa thử nghiệm, tệp được kiểm tra tính hợp lệ nhưng không được lưu, và lượt phân tích trả về ngay một kết quả mẫu cố định. Mã báo cáo của mẫu này bắt đầu bằng `FV-TEST-` và không có trang xác minh công khai.

## 6. Chuyển sang chế độ thật

- Tạo khóa **Thật** trong Console và dùng khóa đó thay cho khóa thử nghiệm. Cùng một đoạn mã vẫn chạy mà không cần sửa.
- Hãy dùng lượt dùng thử miễn phí, hoặc nạp tiền vào số dư không gian làm việc trong **Số dư**. Số tiền nạp tối thiểu là 19 USD.
- Hãy đặt hạn mức chi tiêu hằng tháng cho khóa, và thêm một [endpoint webhook](https://fileverity.com/vi/docs/webhooks.md) thay vì truy vấn định kỳ (polling).
- Hãy gửi `Idempotency-Key` trong các yêu cầu POST để một lần thử lại không bao giờ chạy cùng một lượt kiểm tra hai lần. Xem [Idempotency](https://fileverity.com/vi/docs/idempotency.md).

Để biết mỗi loại kiểm tra phân tích những gì và các đội nhóm dùng ở đâu, hãy xem [API phát hiện ảnh AI](https://fileverity.com/vi/api/phat-hien-anh-ai) và [API phát hiện gian lận tài liệu](https://fileverity.com/vi/api/phat-hien-gia-mao-tai-lieu).

Tiếp theo: [Mã mẫu](https://fileverity.com/vi/docs/sample-code.md) có các chương trình Node.js và Python hoàn chỉnh cho mọi loại kiểm tra và cho webhook. Sau đó hãy đọc [Xác thực và khóa API](https://fileverity.com/vi/docs/authentication.md), [Lỗi](https://fileverity.com/vi/docs/errors.md) và [Tham chiếu API](https://fileverity.com/vi/docs/api-reference.md). Nếu có điều gì không hoạt động, hãy gửi email tới [hello@fileverity.com](mailto:hello@fileverity.com) hoặc dùng [trang liên hệ](https://fileverity.com/vi/lien-he), kèm mã yêu cầu trong header `x-request-id`.