# Phân tích

> Tạo lượt phân tích ảnh và tài liệu, chờ kết quả bằng Prefer: wait hoặc truy vấn định kỳ, hủy, tải báo cáo PDF và đọc đối tượng báo cáo cùng trang xác minh.

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

Một lượt phân tích là một lượt kiểm tra ảnh hoặc tài liệu. Lượt phân tích kiểm tra một tệp đã tải lên bằng `fvimg-2` (ảnh) hoặc `fvdoc-3` (tài liệu). Hãy tải tệp lên trước (xem [Tệp](https://fileverity.com/vi/docs/files.md)), rồi tạo lượt phân tích.

Để xem tổng quan về sản phẩm kèm một yêu cầu và một phản hồi, 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).

## Tạo lượt phân tích

`POST /analyses` trả về đối tượng lượt phân tích. Khoản phí được tạm giữ khi lượt phân tích được tạo và được hoàn lại nếu lượt phân tích thất bại hoặc bị hủy.

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `model` | string | Có | `fvimg-2` hoặc `fvdoc-3`, hoặc mã snapshot như `fvimg-2-2026-10-30`. |
| `file` | string | Có | Mã của một tệp đã tải lên. |
| `metadata` | object | Không | Tối đa 16 cặp chuỗi. Key tối đa 40 ký tự, value tối đa 500. Được trả về trong lượt phân tích và trong webhook. |
| `options.password` | string | Không | Mật khẩu của tài liệu được mã hóa, tối đa 256 ký tự. |
| `options.locale` | string | Không | Ngôn ngữ của các phát hiện về tài liệu: `en`, `fr`, `de`, `es`, `zh`, `vi` hoặc `ar`. Mặc định là `en`. |

**Tạo lượt phân tích: cURL**

```bash
curl https://api.fileverity.com/v1/analyses \
  -H "Authorization: Bearer $FILEVERITY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0e5f6a64-52c2-4b36-9d0d-6f3d2f4c9a10" \
  -d '{"model": "fvdoc-3", "file": "file_Pw3mY6zB8Hk2pQ4vN9sL1xR7", "metadata": {"order_id": "A-10492"}}'
```

**Tạo lượt phân tích: JavaScript**

```javascript
const response = await fetch("https://api.fileverity.com/v1/analyses", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.FILEVERITY_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({ model: "fvdoc-3", file: file.id, metadata: { order_id: "A-10492" } }),
});
const analysis = await response.json();
```

**Tạo lượt phân tích: Python**

```python
import os
import uuid
import requests

response = requests.post(
    "https://api.fileverity.com/v1/analyses",
    headers={
        "Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"],
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"model": "fvdoc-3", "file": file["id"], "metadata": {"order_id": "A-10492"}},
)
analysis = response.json()
```

## Chờ, truy vấn định kỳ hoặc dùng webhook

Yêu cầu tạo trả về `202` kèm `status: processing`. Bạn có ba cách để nhận kết quả:

- **Chờ.** Gửi `Prefer: wait=N`, trong đó N tối đa là 60 giây. Yêu cầu được giữ cho đến khi lượt phân tích hoàn tất hoặc đã qua N giây. Lượt phân tích đã hoàn tất trả về `200`; nếu không, bạn vẫn nhận `202`. Header phản hồi `preference-applied: wait=N` xác nhận thời gian chờ đã được áp dụng.
- **Truy vấn định kỳ.** Gọi `GET /analyses/{id}` sau mỗi vài giây cho đến khi `status` không còn là `processing`.
- **Webhook.** Đăng ký nhận `analysis.completed` và `analysis.failed` rồi lấy lượt phân tích khi sự kiện đến. Xem [Webhook](https://fileverity.com/vi/docs/webhooks.md).

**Truy vấn định kỳ cho đến khi xong: JavaScript**

```javascript
let analysis = created;
while (analysis.status === "processing") {
  await new Promise((resolve) => setTimeout(resolve, 3000));
  const response = await fetch("https://api.fileverity.com/v1/analyses/" + analysis.id, {
    headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY },
  });
  analysis = await response.json();
}
```

**Truy vấn định kỳ cho đến khi xong: Python**

```python
import time

analysis = created
while analysis["status"] == "processing":
    time.sleep(3)
    analysis = requests.get("https://api.fileverity.com/v1/analyses/" + analysis["id"], headers=headers).json()
```

**202 Accepted, tài liệu**

```json
{
  "id": "an_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "analysis",
  "created": 1793700120,
  "model": "fvdoc-3-2026-11-03",
  "livemode": true,
  "status": "processing",
  "file": {
    "name": "contract.pdf",
    "bytes": 18874368,
    "format": "pdf"
  },
  "report_id": null,
  "report_url": null,
  "summary": null,
  "result": null,
  "error": null,
  "progress": {
    "stage": "queued",
    "done": 0,
    "total": 0,
    "position": 1
  },
  "usage": {
    "amount": 599,
    "currency": "usd",
    "funding": "balance"
  },
  "metadata": {
    "order_id": "A-10492"
  },
  "completed_at": null,
  "expires_at": null
}
```

Trong khi một lượt phân tích đang xử lý, `progress.stage` là một trong các giá trị `queued`, `reading`, `analyzing` hoặc `reporting`, và `position` là vị trí trong hàng đợi khi giai đoạn là `queued`. Tài liệu có thể phải xếp hàng chờ. Việc chờ kết quả là tùy chọn đối với tài liệu và có thể kết thúc trước khi kết quả sẵn sàng, vì vậy hãy luôn xử lý `202`.

## Khi dịch vụ đang bận

Khi công suất xử lý đang bận, `POST /analyses` trả về `503` với mã `service_unavailable` và header `retry-after`. Bạn không bị tính phí. Hãy chờ số giây ghi trong `retry-after`, rồi thử lại với cùng `Idempotency-Key` để lần thử lại không bao giờ chạy cùng một lượt kiểm tra hai lần. Để đạt thông lượng tốt nhất, hãy chạy các lượt phân tích ảnh lần lượt thay vì song song.

**Thử lại khi dịch vụ bận: JavaScript**

```javascript
async function create(body, key) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const response = await fetch("https://api.fileverity.com/v1/analyses", {
      method: "POST",
      headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY, "Content-Type": "application/json", "Idempotency-Key": key },
      body: JSON.stringify(body),
    });
    if (response.status !== 503) return response;
    const wait = Number(response.headers.get("retry-after")) || 15;
    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
  }
  throw new Error("Service busy");
}
```

**Thử lại khi dịch vụ bận: Python**

```python
import time

def create(body, key):
    for attempt in range(5):
        response = requests.post("https://api.fileverity.com/v1/analyses", headers={**headers, "Idempotency-Key": key}, json=body)
        if response.status_code != 503:
            return response
        time.sleep(int(response.headers.get("retry-after", 15)))
    raise RuntimeError("Service busy")
```

## Trạng thái

| Trạng thái | Ý nghĩa |
| --- | --- |
| `processing` | Lượt phân tích đang chạy. `result` là `null`. |
| `succeeded` | Kết quả đã sẵn sàng. `report_id`, `report_url`, `summary` và `result` đều có giá trị. |
| `failed` | Không thể hoàn tất lượt phân tích. `error` chứa `code` và `message`. Bạn không bị tính phí. |
| `canceled` | Bạn đã hủy lượt phân tích. `error.code` là `canceled`. Bạn không bị tính phí. |

**Lượt phân tích thất bại**

```json
{
  "id": "an_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "analysis",
  "created": 1793700120,
  "model": "fvimg-2-2026-10-30",
  "livemode": true,
  "status": "failed",
  "file": {
    "name": "claim-photo.jpg",
    "bytes": 2481920,
    "format": "jpeg"
  },
  "report_id": null,
  "report_url": null,
  "summary": null,
  "result": null,
  "error": {
    "code": "analysis_failed",
    "message": "The analysis could not be completed. You were not charged; retry it, and contact support with the request ID if it fails again."
  },
  "progress": null,
  "usage": {
    "amount": 0,
    "currency": "usd",
    "funding": null
  },
  "metadata": null,
  "completed_at": 1793700135,
  "expires_at": null
}
```

## Đối tượng báo cáo

Lượt phân tích thành công chứa đúng báo cáo mà website, PDF và trang xác minh hiển thị.

| Trường | Mô tả |
| --- | --- |
| `report_id` | Mã báo cáo, `FV-XXXX-XXXX-XXXX`. |
| `report_url` | Trang xác minh công khai của báo cáo. Bất kỳ ai có liên kết đều có thể đối chiếu mã báo cáo, giá trị băm của tệp và dấu thời gian với bản ghi mà không cần tài khoản. |
| `summary` | Kết luận ngắn gọn. Xem bên dưới. |
| `result.report` | Báo cáo đầy đủ. `result.report.schema` là `fileverity.report/1` với ảnh và `fileverity.docpro/1` với tài liệu. |
| `result.stamped_at` | Dấu thời gian Unix của dấu thời gian RFC 3161 được cấp cho báo cáo, hoặc `null`. |
| `usage` | `amount` đã tính phí, tính bằng cent (bằng 0 với lượt kiểm tra dùng thử miễn phí và lượt thất bại), `currency` và `funding` (`trial` hoặc `balance`). |
| `metadata` | Metadata bạn đã gửi, hoặc `null`. |
| `expires_at` | Dấu thời gian Unix mà sau đó `result` bị xóa. Kết quả được lưu giữ trong 7 ngày. |

**200 OK, ảnh**

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

Đối tượng `report` ở trên đã được rút gọn; đối tượng thật chứa đầy đủ các phát hiện.

`summary` là kết luận ổn định, ở dạng máy đọc được. `result.report` là báo cáo đầy đủ mà website và PDF hiển thị. Cấu trúc của báo cáo tuân theo schema được nêu trong `result.report.schema`. Trong cùng một phiên bản schema, các trường đã liệt kê giữ nguyên tên và ý nghĩa, và có thể bổ sung trường mới, vì vậy hãy bỏ qua các trường bạn không nhận ra.

### Tóm tắt ảnh

| Trường | Giá trị |
| --- | --- |
| `level` | `L0` Chưa xác định, `L1` Đã xác minh nguồn, `L2` Không phát hiện bất thường, `L3` Cần xem xét thủ công, `L4` Rất đáng ngờ, `L5` Bằng chứng mạnh cho thấy ảnh không xác thực. |
| `action` | `accept`, `review`, `reject`, `resubmit` |
| `assessment` | `authentic_untouched`, `authentic_locally_edited`, `ai_generated`, `undetermined` |
| `ai` | `labelled`, `very_likely`, `suspected`, `undecided`, `low`, `very_low`, `not_evaluated` |
| `edit` | `detected`, `suspected`, `suspected_record`, `review`, `generative`, `minor`, `none`, `not_applicable`, `not_evaluated` |

### Tóm tắt tài liệu

| Trường | Mô tả |
| --- | --- |
| `kind` | Luôn là `docpro`. |
| `level` | `L0` Chưa xác định, `L1` Nguồn gốc đã xác minh, `L2` Không có dấu hiệu can thiệp, `L3` Cần xem xét thủ công, `L4` Rủi ro cao, `L5` Đã xác định có vấn đề. |
| `action` | `accept`, `note` (đối chiếu nội dung AI được đánh dấu trong báo cáo với chính sách của bạn), `review`, `reject` hoặc `resubmit`. |
| `reason` | Phát hiện hoặc điều kiện dẫn đến mức này, ví dụ `clean`, `incomplete` hoặc mã của một phát hiện, hoặc `null`. |
| `findings` | Mã của các phát hiện quan trọng. |
| `pages`, `images` | Số trang của tài liệu và số ảnh nhúng đã kiểm tra. |
| `text` | Kết luận về văn bản của tài liệu (`ai_generated`, `mixed`, `human`, `inconclusive`), hoặc `null` khi văn bản không được đánh giá. |
| `strong` | `true` khi một phát hiện được liệt kê là mạnh. Trường này không xuất hiện trong các trường hợp khác. |

**200 OK, tài liệu**

```json
{
  "id": "an_Zc4vB7nP1sK8tL3wR6yQm2Xa",
  "object": "analysis",
  "created": 1793700300,
  "model": "fvdoc-3-2026-11-03",
  "livemode": true,
  "status": "succeeded",
  "file": {
    "name": "contract.pdf",
    "bytes": 18874368,
    "format": "pdf"
  },
  "report_id": "FV-3PXH-6WQ2-8NDC",
  "report_url": "https://fileverity.com/verify/FV-3PXH-6WQ2-8NDC",
  "summary": {
    "kind": "docpro",
    "level": "L3",
    "action": "review",
    "reason": null,
    "findings": [],
    "pages": 12,
    "images": 3,
    "text": "human"
  },
  "result": {
    "report": {
      "schema": "fileverity.docpro/1",
      "id": "FV-3PXH-6WQ2-8NDC"
    },
    "stamped_at": 1793700340
  },
  "error": null,
  "progress": null,
  "usage": {
    "amount": 599,
    "currency": "usd",
    "funding": "balance"
  },
  "metadata": null,
  "completed_at": 1793700341,
  "expires_at": 1794305141
}
```

### Các trường của báo cáo ảnh

`result.report` của một lượt phân tích ảnh. Các đối tượng lồng nhau được liệt kê trong [Tham chiếu API](https://fileverity.com/vi/docs/api-reference.md#create-analysis).

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `schema` | `"fileverity.report/1"` | Có |  |
| `id` | string | Có | Mã báo cáo, FV-XXXX-XXXX-XXXX. |
| `sample` | `true` | Không | Có trong các báo cáo mẫu cố định mà khóa thử nghiệm trả về. |
| `issuedAt` | string | Không | Thời điểm báo cáo được cấp, theo ISO 8601 ở UTC. Định dạng date-time. |
| `issuer` | object | Không | Đơn vị cấp báo cáo. |
| `file` | object | Không | Ảnh đã được kiểm tra. |
| `pro` | object | Không | Kết luận. Cùng các giá trị như summary, kèm lý do. |
| `score` | integer hoặc null | Không | Điểm xác thực từ 0 đến 100, với bước nhảy 5: bằng chứng ủng hộ mạnh đến đâu việc ảnh là một ảnh chụp xác thực, chưa qua chỉnh sửa. null khi không được đánh giá. |
| `confidence` | một trong `"high"`, `"medium"`, `"low"` | Không | Mức độ mà tệp này cho phép lượt phân tích xác lập được. Mức tin cậy thấp thường phản ánh chính tệp, chẳng hạn độ phân giải thấp hoặc nén mạnh. |
| `questions` | object | Không | Ba câu hỏi mà báo cáo trả lời. |
| `generator` | object hoặc null | Không | Công cụ tạo ảnh AI được nêu cho ảnh này, hoặc null. |
| `regions` | mảng object | Không | Các vùng được đánh dấu, tính bằng điểm ảnh của ảnh được hiển thị. |
| `provenance` | object | Không | Những gì chính các bản ghi của tệp cho biết về nguồn gốc của tệp. |
| `digest` | string | Không | Giá trị băm của nội dung báo cáo, được trang xác minh sử dụng. |

### Các trường của báo cáo tài liệu

`result.report` của một lượt phân tích tài liệu.

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `schema` | `"fileverity.docpro/1"` | Có |  |
| `id` | string | Có | Mã báo cáo, FV-XXXX-XXXX-XXXX. |
| `sample` | `true` | Không | Có trong các báo cáo mẫu cố định mà khóa thử nghiệm trả về. |
| `issuedAt` | string | Không | Thời điểm báo cáo được cấp, theo ISO 8601 ở UTC. Định dạng date-time. |
| `receivedAt` | string | Không | Thời điểm nhận tệp, theo ISO 8601 ở UTC. Định dạng date-time. |
| `issuer` | object | Không | Đơn vị cấp báo cáo. |
| `file` | object | Không | Tài liệu đã được kiểm tra. |
| `level` | một trong `"L0"`, `"L1"`, `"L2"`, `"L3"`, `"L4"`, `"L5"` | Không | Mức độ rủi ro, từ L0 đến L5. |
| `action` | một trong `"accept"`, `"note"`, `"review"`, `"reject"`, `"resubmit"` | Không |  |
| `reason` | string hoặc null | Không | Phát hiện hoặc điều kiện dẫn đến mức này. |
| `findings` | mảng object | Không | Các phát hiện dẫn đến mức này, mỗi phát hiện kèm các trang và ảnh nhúng mà nó đề cập. |
| `text` | object | Không | Kết quả cho văn bản của tài liệu. |
| `images` | mảng object | Không | Các ảnh và hình đồ họa nhúng, được đánh số theo thứ tự trong tài liệu. |
| `structure` | object hoặc null | Không | Lịch sử chỉnh sửa của tệp, hoặc null khi chưa được kiểm tra. |
| `provenance` | object | Không | Những gì chính các bản ghi của tệp cho biết về nguồn gốc của tệp. |
| `digest` | string | Không | Giá trị băm của nội dung báo cáo, được trang xác minh sử dụng. |

## Lấy, liệt kê và hủy

- `GET /analyses/{id}` trả về lượt phân tích, kèm kết quả khi kết quả còn được lưu giữ.
- `GET /analyses` liệt kê các lượt phân tích của không gian làm việc, mới nhất trước. `limit` từ 1 đến 100 (mặc định 20), `type` lọc theo `image` hoặc `document`, và `starting_after` nhận `next_cursor` của trang trước. Các mục trong danh sách không bao giờ có `result`.
- `POST /analyses/{id}/cancel` hủy một lượt phân tích tài liệu đang xử lý và hoàn lại khoản phí đã tạm giữ. Không thể hủy lượt phân tích ảnh; yêu cầu hủy quá muộn hoặc khi lượt phân tích đã hoàn tất sẽ trả về `not_cancelable`.

**Liệt kê và hủy: cURL**

```bash
curl "https://api.fileverity.com/v1/analyses?limit=20&type=document" \
  -H "Authorization: Bearer $FILEVERITY_API_KEY"

curl -X POST https://api.fileverity.com/v1/analyses/an_8Hk2pQ4vN9sL1xR7cW3mY6zB/cancel \
  -H "Authorization: Bearer $FILEVERITY_API_KEY"
```

## Báo cáo PDF

`GET /analyses/{id}/report.pdf` tải xuống báo cáo PDF có dấu niêm phong của một lượt phân tích thành công khi kết quả còn được lưu giữ. Thêm `?locale=` với `en`, `fr`, `de`, `es`, `zh`, `vi` hoặc `ar` (mặc định `en`). Gửi header `Authorization`; phản hồi là `application/pdf`.

**Tải xuống PDF: cURL**

```bash
curl "https://api.fileverity.com/v1/analyses/an_8Hk2pQ4vN9sL1xR7cW3mY6zB/report.pdf?locale=en" \
  -H "Authorization: Bearer $FILEVERITY_API_KEY" \
  -o Fileverity-FV-7K2M-9QXD-4T8R.pdf
```

Với tài liệu, ảnh các trang và đoạn trích văn bản được giữ trong 3 giờ sau lượt kiểm tra. Sau đó PDF sẽ không còn chứa chúng, và header phản hồi `x-evidence-included` có giá trị `false`. Hãy tải PDF ngay khi lượt phân tích hoàn tất nếu bạn cần PDF bao gồm cả bằng chứng.

## Lỗi

| Mã lỗi | Trạng thái | Nguyên nhân |
| --- | --- | --- |
| `file_not_found` | 400 | Mã tệp không tồn tại, đã hết hạn hoặc đã được sử dụng, hoặc quá trình tải lên `upload.url` chưa hoàn tất. |
| `model_not_found` | 404 | Mô hình không tồn tại. |
| `invalid_parameter` | 400 | Một trường bị thiếu, sai kiểu dữ liệu hoặc không xác định. Các mô hình văn bản dùng với `POST /text/detections`. |
| `unsupported_file`, `invalid_file` | 415, 422 | Định dạng tệp không được hỗ trợ cho mô hình này, hoặc tệp bị hỏng. |
| `file_too_large`, `too_many_pixels`, `too_many_pages`, `document_too_long` | 413 | Vượt quá một giới hạn kích thước. |
| `password_required`, `wrong_password` | 422 | Tài liệu đã được mã hóa. Hãy gửi `options.password`. |
| `not_examinable` | 422 | Tài liệu không có nội dung nào có thể kiểm tra. Không tính phí. |
| `insufficient_balance`, `spend_limit_reached` | 402 | Số dư hoặc hạn mức hằng tháng của khóa không đủ để chi trả mức giá này. |
| `service_unavailable`, `analysis_failed` | 503, 502 | Lỗi tạm thời hoặc công suất xử lý đang bận. Không tính phí; hãy thử lại. `service_unavailable` có kèm header `retry-after`. Xem [Khi dịch vụ đang bận](https://fileverity.com/vi/docs/analyses.md#busy). |
| `unsupported_media_type` | 415 | Nội dung yêu cầu không được gửi dưới dạng `application/json`. |
| `idempotency_mismatch`, `idempotency_in_progress` | 409 | `Idempotency-Key` đã được dùng với nội dung 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. Xem [Idempotency](https://fileverity.com/vi/docs/idempotency.md). |
| `not_cancelable` | 409 | Chỉ có thể hủy lượt phân tích tài liệu vẫn đang được xử lý. |

> **Lưu ý.** Một số lỗi xảy ra sau khi lượt phân tích đã được tạo, chẳng hạn khi một mô hình không thể hoàn tất. Các lỗi này đặt `status: failed` và `error` cho lượt phân tích thay vì khiến lệnh tạo thất bại, và webhook `analysis.failed` được kích hoạt. Xem [Lỗi](https://fileverity.com/vi/docs/errors.md).