# Tham chiếu API

> Mọi endpoint của Fileverity API với tham số, schema yêu cầu và phản hồi, mã lỗi và ví dụ, được tạo từ đặc tả OpenAPI 3.1.

Nguồn: https://fileverity.com/vi/docs/api-reference

Tài liệu tham chiếu này được tạo từ tài liệu OpenAPI 3.1 của API, có tại [https://api.fileverity.com/v1/openapi.json](https://api.fileverity.com/v1/openapi.json), nên luôn khớp với API. Để tìm hiểu các khái niệm và hướng dẫn, hãy bắt đầu từ [Tổng quan](https://fileverity.com/vi/docs.md).

## Quy ước

Base URL: `https://api.fileverity.com/v1`. Xác thực mọi yêu cầu bằng `Authorization: Bearer <key>`. Các lỗi dùng chung một định dạng, được mô tả trong [Lỗi](https://fileverity.com/vi/docs/errors.md). Mọi phản hồi đều có header `x-request-id`, và các phản hồi đã xác thực có kèm các header giới hạn tốc độ được mô tả trong [Giới hạn tốc độ và header](https://fileverity.com/vi/docs/rate-limits.md). Các đối tượng lồng nhau mở ra trong các mục có thể thu gọn bên dưới bảng.

## Phát hiện văn bản

### Phát hiện văn bản do AI viết

`POST` `https://api.fileverity.com/v1/text/detections`

Phân loại văn bản thuần túy là do AI viết, một phần do AI viết hoặc do người viết, và trả về các đoạn do AI viết. Văn bản được đánh giá rồi loại bỏ; văn bản không được lưu. Việc tính phí đếm code point Unicode theo đơn vị 1.000 ký tự, làm tròn lên cho mỗi yêu cầu. Các yêu cầu bị từ chối trước khi đánh giá không bị tính phí. Khóa thử nghiệm trả về một kết quả cố định là văn bản do người viết và không bị tính phí.

#### Tham số

| Tên | Vị trí | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | Không | Khóa duy nhất tối đa 255 ký tự. Gửi lại yêu cầu với cùng khóa và cùng nội dung trong vòng 24 giờ sẽ trả về phản hồi đầu tiên kèm header idempotent-replayed: true; cùng khóa nhưng nội dung khác trả về 409. |

#### Nội dung yêu cầu: application/json, bắt buộc

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `model` | string | Không | Mã mô hình hoặc mã snapshot. Mặc định `"fvdoc-3-text"`. |
| `text` | string | Có | Văn bản thuần túy, tối thiểu 100 từ và tối đa 100.000 ký tự. |
| `language` | một trong `"en"`, `"fr"`, `"de"`, `"es"`, `"zh"`, `null` | Không | Mã ISO 639-1. Tự động nhận diện nếu không truyền. Mặc định `null`. |

#### Phản hồi

| Trạng thái | Mô tả | Nội dung |
| --- | --- | --- |
| 200 | Kết quả phát hiện. | `TextDetection` |
| 400 | Yêu cầu không hợp lệ. Mã lỗi: invalid_json, missing_parameter, text_too_short, unsupported_language, invalid_parameter. | `Error` |
| 401 | Thiếu khóa API hoặc khóa API không hợp lệ. Mã lỗi: missing_api_key, invalid_api_key. | `Error` |
| 402 | Số dư hoặc hạn mức chi tiêu hằng tháng của khóa không đủ cho yêu cầu. Mã lỗi: insufficient_balance, spend_limit_reached. | `Error` |
| 404 | Không tìm thấy tài nguyên. Mã lỗi: model_not_found. | `Error` |
| 409 | Xung đột với trạng thái hiện tại. Mã lỗi: idempotency_mismatch, idempotency_in_progress. | `Error` |
| 413 | Vượt quá giới hạn kích thước. Mã lỗi: text_too_long. | `Error` |
| 415 | Media type hoặc định dạng tệp không được hỗ trợ. Mã lỗi: unsupported_media_type. | `Error` |
| 429 | Quá nhiều yêu cầu. Mã lỗi: rate_limited. | `Error` |
| 500 | Lỗi nội bộ; không bị tính phí. Mã lỗi: internal_error. | `Error` |
| 502 | Không thể hoàn tất lượt phân tích; không bị tính phí. Mã lỗi: analysis_failed. | `Error` |
| 503 | Tạm thời không khả dụng hoặc đang bận; không bị tính phí. Hãy thử lại sau số giây ghi trong header retry-after. Mã lỗi: service_unavailable. | `Error` |

#### Phản hồi 200: TextDetection

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `id` | string | Có |  |
| `object` | `"text.detection"` | Có |  |
| `created` | integer | Có | Dấu thời gian Unix. |
| `model` | string | Có | Snapshot đã tạo ra kết quả. |
| `livemode` | boolean | Có | False đối với khóa thử nghiệm. |
| `language` | một trong `"en"`, `"fr"`, `"de"`, `"es"`, `"zh"` | Có |  |
| `verdict` | một trong `"ai"`, `"mixed"`, `"human"` | Có | ai: toàn bộ văn bản có vẻ do AI viết; mixed: có các đoạn do AI viết trong văn bản do người viết; human: không tìm thấy đoạn nào do AI viết. |
| `score` | number | Có | Điểm của mô hình cho đoạn giống văn bản do AI viết nhất. Tối thiểu 0. Tối đa 1. |
| `ai_fraction` | number | Có | Tỷ lệ văn bản được đánh giá nằm trong các đoạn do AI viết. Tối thiểu 0. Tối đa 1. |
| `segments` | mảng object | Có | Các đoạn do AI viết, dưới dạng vị trí (offset) trong văn bản đã gửi, tính theo code point Unicode. Ranh giới mang tính tương đối và có thể bao gồm các câu liền kề. |
| `usage` | object | Có |  |

**segments: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `start` | integer | Có |  |
| `end` | integer | Có | Không bao gồm (exclusive). |
| `score` | number | Có | Tối thiểu 0. Tối đa 1. |

**usage: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `characters` | integer | Có | Số code point Unicode đã được đánh giá. |
| `free_characters` | integer | Có | Số ký tự nằm trong phần lượt dùng thử miễn phí của bạn, không bị tính phí. |
| `billed_units` | integer | Có | Số đơn vị 1.000 ký tự thực tế bị tính phí, sau khi trừ ký tự miễn phí; billed_units × đơn giá là chi phí. |

#### Mã lỗi

| Mã lỗi | Trạng thái |
| --- | --- |
| `invalid_json` | 400 |
| `missing_parameter` | 400 |
| `unsupported_media_type` | 415 |
| `text_too_short` | 400 |
| `text_too_long` | 413 |
| `unsupported_language` | 400 |
| `model_not_found` | 404 |
| `insufficient_balance` | 402 |
| `spend_limit_reached` | 402 |
| `service_unavailable` | 503 |
| `analysis_failed` | 502 |
| `invalid_parameter` | 400 |
| `idempotency_mismatch` | 409 |
| `idempotency_in_progress` | 409 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Ví dụ

**Yêu cầu: 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)"
```

**Phản hồi**

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

## Tệp

### Tải tệp lên

`POST` `https://api.fileverity.com/v1/files`

Tải một tệp lên để phân tích. Gửi các tệp tối đa 4 MB dưới dạng multipart/form-data trong trường file; phản hồi có trạng thái uploaded. Các tệp lớn hơn 4 MB phải được tải lên bằng URL ký trước (pre-signed URL). Gửi JSON gồm filename, content_type và bytes (tài liệu tối đa 50 MB); phản hồi có trạng thái pending và một đối tượng upload chứa URL ký trước: hãy gửi các byte của tệp tới URL đó bằng PUT cùng các header đã cho trước khi URL hết hạn. Tệp bị xóa khi một lượt phân tích bắt đầu và chậm nhất sau 24 giờ. Một không gian làm việc có thể giữ tối đa 50 tệp chưa hết hạn và 200 MB cho mỗi chế độ cùng lúc.

#### Tham số

| Tên | Vị trí | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | Không | Khóa duy nhất tối đa 255 ký tự. Gửi lại yêu cầu với cùng khóa và cùng nội dung trong vòng 24 giờ sẽ trả về phản hồi đầu tiên kèm header idempotent-replayed: true; cùng khóa nhưng nội dung khác trả về 409. |

#### Nội dung yêu cầu: multipart/form-data, bắt buộc

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `file` | string | Có | Định dạng binary. |

#### Nội dung yêu cầu: application/json, bắt buộc

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `filename` | string | Không |  |
| `content_type` | string | Có | MIME type của tệp, ví dụ image/jpeg hoặc application/pdf. |
| `bytes` | integer | Có | Kích thước chính xác tính bằng byte. Tối thiểu 1. Tối đa 52.428.800. |

#### Phản hồi

| Trạng thái | Mô tả | Nội dung |
| --- | --- | --- |
| 201 | Tệp. | `File` |
| 400 | Yêu cầu không hợp lệ. Mã lỗi: invalid_json, missing_parameter, invalid_parameter. | `Error` |
| 401 | Thiếu khóa API hoặc khóa API không hợp lệ. Mã lỗi: missing_api_key, invalid_api_key. | `Error` |
| 409 | Xung đột với trạng thái hiện tại. Mã lỗi: idempotency_mismatch, idempotency_in_progress. | `Error` |
| 413 | Vượt quá giới hạn kích thước. Mã lỗi: file_too_large. | `Error` |
| 415 | Media type hoặc định dạng tệp không được hỗ trợ. Mã lỗi: unsupported_media_type, unsupported_file. | `Error` |
| 422 | Không thể xử lý tệp. Mã lỗi: invalid_file. | `Error` |
| 429 | Quá nhiều yêu cầu. Mã lỗi: pending_files_limit, rate_limited. | `Error` |
| 500 | Lỗi nội bộ; không bị tính phí. Mã lỗi: internal_error. | `Error` |

#### Phản hồi 201: File

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `id` | string | Có |  |
| `object` | `"file"` | Có |  |
| `filename` | string hoặc null | Có |  |
| `bytes` | integer hoặc null | Có |  |
| `content_type` | string | Có |  |
| `status` | một trong `"pending"`, `"uploaded"` | Có | pending cho đến khi các byte gửi tới URL ký trước đã được nhận đủ. |
| `livemode` | boolean | Có | Tệp chỉ hiển thị với các khóa cùng chế độ. |
| `created` | integer | Có | Dấu thời gian Unix. |
| `expires_at` | integer | Có | Dấu thời gian Unix mà sau đó tệp bị xóa. |
| `upload` | object | Không | Có trong phản hồi cho yêu cầu tải lên dạng JSON. |

**upload: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `url` | string | Có | Khóa thử nghiệm nhận một URL giữ chỗ (test: true); không có gì được tải lên hoặc lưu. |
| `method` | `"PUT"` | Có |  |
| `headers` | object có giá trị string | Có |  |
| `expires_at` | integer | Có | Dấu thời gian Unix. |
| `test` | `true` | Không |  |

#### Mã lỗi

| Mã lỗi | Trạng thái |
| --- | --- |
| `invalid_json` | 400 |
| `missing_parameter` | 400 |
| `unsupported_media_type` | 415 |
| `unsupported_file` | 415 |
| `invalid_file` | 422 |
| `file_too_large` | 413 |
| `pending_files_limit` | 429 |
| `invalid_parameter` | 400 |
| `idempotency_mismatch` | 409 |
| `idempotency_in_progress` | 409 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Ví dụ

**Yêu cầu: cURL**

```bash
curl https://api.fileverity.com/v1/files \
  -H "Authorization: Bearer $FILEVERITY_API_KEY" \
  -F file=@claim-photo.jpg
```

**Phản hồi**

```json
{
  "id": "file_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "file",
  "filename": "claim-photo.jpg",
  "bytes": 2481920,
  "content_type": "image/jpeg",
  "status": "uploaded",
  "livemode": true,
  "created": 1793700000,
  "expires_at": 1793786400
}
```

### Lấy thông tin tệp

`GET` `https://api.fileverity.com/v1/files/{id}`

Trả về tệp và cho biết các byte của tệp đã được nhận đủ hay chưa.

#### Tham số

| Tên | Vị trí | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- | --- |
| `id` | path | string | Có | Mã tệp. |

#### Phản hồi

| Trạng thái | Mô tả | Nội dung |
| --- | --- | --- |
| 200 | Tệp. | `File` |
| 401 | Thiếu khóa API hoặc khóa API không hợp lệ. Mã lỗi: missing_api_key, invalid_api_key. | `Error` |
| 404 | Không tìm thấy tài nguyên. Mã lỗi: not_found. | `Error` |
| 429 | Quá nhiều yêu cầu. Mã lỗi: rate_limited. | `Error` |
| 500 | Lỗi nội bộ; không bị tính phí. Mã lỗi: internal_error. | `Error` |

#### Phản hồi 200: File

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `id` | string | Có |  |
| `object` | `"file"` | Có |  |
| `filename` | string hoặc null | Có |  |
| `bytes` | integer hoặc null | Có |  |
| `content_type` | string | Có |  |
| `status` | một trong `"pending"`, `"uploaded"` | Có | pending cho đến khi các byte gửi tới URL ký trước đã được nhận đủ. |
| `livemode` | boolean | Có | Tệp chỉ hiển thị với các khóa cùng chế độ. |
| `created` | integer | Có | Dấu thời gian Unix. |
| `expires_at` | integer | Có | Dấu thời gian Unix mà sau đó tệp bị xóa. |
| `upload` | object | Không | Có trong phản hồi cho yêu cầu tải lên dạng JSON. |

**upload: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `url` | string | Có | Khóa thử nghiệm nhận một URL giữ chỗ (test: true); không có gì được tải lên hoặc lưu. |
| `method` | `"PUT"` | Có |  |
| `headers` | object có giá trị string | Có |  |
| `expires_at` | integer | Có | Dấu thời gian Unix. |
| `test` | `true` | Không |  |

#### Mã lỗi

| Mã lỗi | Trạng thái |
| --- | --- |
| `not_found` | 404 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Ví dụ

**Yêu cầu: cURL**

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

**Phản hồi**

```json
{
  "id": "file_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "file",
  "filename": "claim-photo.jpg",
  "bytes": 2481920,
  "content_type": "image/jpeg",
  "status": "uploaded",
  "livemode": true,
  "created": 1793700000,
  "expires_at": 1793786400
}
```

### Xóa một tệp

`DELETE` `https://api.fileverity.com/v1/files/{id}`

Xóa một tệp đã tải lên cùng các byte đã lưu của tệp đó.

#### Tham số

| Tên | Vị trí | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- | --- |
| `id` | path | string | Có | Mã tệp. |

#### Phản hồi

| Trạng thái | Mô tả | Nội dung |
| --- | --- | --- |
| 200 | Tệp đã bị xóa. | `FileDeleted` |
| 401 | Thiếu khóa API hoặc khóa API không hợp lệ. Mã lỗi: missing_api_key, invalid_api_key. | `Error` |
| 404 | Không tìm thấy tài nguyên. Mã lỗi: not_found. | `Error` |
| 429 | Quá nhiều yêu cầu. Mã lỗi: rate_limited. | `Error` |
| 500 | Lỗi nội bộ; không bị tính phí. Mã lỗi: internal_error. | `Error` |

#### Phản hồi 200: FileDeleted

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `id` | string | Có |  |
| `object` | `"file"` | Có |  |
| `deleted` | `true` | Có |  |

#### Mã lỗi

| Mã lỗi | Trạng thái |
| --- | --- |
| `not_found` | 404 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Ví dụ

**Yêu cầu: cURL**

```bash
curl -X DELETE https://api.fileverity.com/v1/files/file_8Hk2pQ4vN9sL1xR7cW3mY6zB \
  -H "Authorization: Bearer $FILEVERITY_API_KEY"
```

**Phản hồi**

```json
{
  "id": "file_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "file",
  "deleted": true
}
```

## Phân tích

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

`POST` `https://api.fileverity.com/v1/analyses`

Phân tích một tệp đã tải lên bằng fvimg-2 (ảnh) hoặc fvdoc-3 (tài liệu). Một lượt phân tích là một lượt kiểm tra ảnh hoặc tài liệu. Phản hồi là 202 với trạng thái processing; kết quả được gửi qua webhook hoặc bằng cách truy vấn định kỳ GET /analyses/{id}. Gửi Prefer: wait=N (tối đa 60 giây) để giữ yêu cầu cho đến khi có kết quả; một lượt phân tích đã hoàn tất trả về 200. Giá đượ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. Kết quả được giữ trong 7 ngày. Khi hệ thống đang bận, API trả về 503 service_unavailable kèm header retry-after và không tính phí: hãy thử lại với cùng Idempotency-Key, và chạy lần lượt từng lượt phân tích ảnh để đạt thông lượng tốt nhất. Khóa thử nghiệm trả về kết quả mẫu và không bao giờ bị tính phí; báo cáo mẫu chỉ chứa một vài trường.

#### Tham số

| Tên | Vị trí | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | Không | Khóa duy nhất tối đa 255 ký tự. Gửi lại yêu cầu với cùng khóa và cùng nội dung trong vòng 24 giờ sẽ trả về phản hồi đầu tiên kèm header idempotent-replayed: true; cùng khóa nhưng nội dung khác trả về 409. |
| `Prefer` | header | string | Không | wait=N giữ yêu cầu tối đa N giây (tối đa 60) cho đến khi lượt phân tích hoàn tất. |

#### Nội dung yêu cầu: application/json, bắt buộc

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `model` | một trong `"fvimg-2"`, `"fvimg-2-2026-10-30"`, `"fvdoc-3"`, `"fvdoc-3-2026-11-03"` | Có | Mã mô hình hoặc mã snapshot. fvimg-2 phân tích ảnh, fvdoc-3 phân tích tài liệu. |
| `file` | string | Có | Mã của một tệp đã tải lên. |
| `metadata` | object có giá trị string | 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` | object | Không |  |

**options: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `password` | string | Không | Mật khẩu của tài liệu đã mã hóa. Độ dài tối đa 256. |
| `locale` | một trong `"en"`, `"fr"`, `"de"`, `"es"`, `"zh"`, `"vi"`, `"ar"` | Không | Ngôn ngữ của các phát hiện về tài liệu. Mặc định `"en"`. |

#### Phản hồi

| Trạng thái | Mô tả | Nội dung |
| --- | --- | --- |
| 200 | Lượt phân tích đã hoàn tất. | `Analysis` |
| 202 | Lượt phân tích đang được xử lý. | `Analysis` |
| 400 | Yêu cầu không hợp lệ. Mã lỗi: invalid_json, missing_parameter, file_not_found, invalid_parameter. | `Error` |
| 401 | Thiếu khóa API hoặc khóa API không hợp lệ. Mã lỗi: missing_api_key, invalid_api_key. | `Error` |
| 402 | Số dư hoặc hạn mức chi tiêu hằng tháng của khóa không đủ cho yêu cầu. Mã lỗi: insufficient_balance, spend_limit_reached. | `Error` |
| 404 | Không tìm thấy tài nguyên. Mã lỗi: model_not_found. | `Error` |
| 409 | Xung đột với trạng thái hiện tại. Mã lỗi: idempotency_mismatch, idempotency_in_progress. | `Error` |
| 413 | Vượt quá giới hạn kích thước. Mã lỗi: file_too_large, too_many_pixels, too_many_pages, document_too_long. | `Error` |
| 415 | Media type hoặc định dạng tệp không được hỗ trợ. Mã lỗi: unsupported_media_type, unsupported_file. | `Error` |
| 422 | Không thể xử lý tệp. Mã lỗi: invalid_file, password_required, wrong_password, not_examinable. | `Error` |
| 429 | Quá nhiều yêu cầu. Mã lỗi: rate_limited. | `Error` |
| 500 | Lỗi nội bộ; không bị tính phí. Mã lỗi: internal_error. | `Error` |
| 502 | Không thể hoàn tất lượt phân tích; không bị tính phí. Mã lỗi: analysis_failed. | `Error` |
| 503 | Tạm thời không khả dụng hoặc đang bận; không bị tính phí. Hãy thử lại sau số giây ghi trong header retry-after. Mã lỗi: service_unavailable. | `Error` |

#### Phản hồi 200: Analysis

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `id` | string | Có |  |
| `object` | `"analysis"` | Có |  |
| `created` | integer | Có | Dấu thời gian Unix. |
| `model` | string | Có | Snapshot đã tạo ra kết quả. |
| `livemode` | boolean | Có |  |
| `status` | một trong `"processing"`, `"succeeded"`, `"failed"`, `"canceled"` | Có |  |
| `file` | object | Có |  |
| `report_id` | string hoặc null | Có | Mã báo cáo có thể xác minh, FV-XXXX-XXXX-XXXX. |
| `report_url` | string hoặc null | Có | Trang xác minh công khai của báo cáo. |
| `summary` | `ImageSummary` hoặc `DocumentSummary` hoặc null | Có | Kết luận ngắn gọn, ổn định: ImageSummary cho ảnh, DocumentSummary cho tài liệu, null cho đến khi lượt phân tích thành công. |
| `result` | object hoặc null | Có | Xuất hiện khi status là succeeded và cho đến khi kết quả hết hạn. |
| `error` | object hoặc null | Có |  |
| `progress` | object hoặc null | Có |  |
| `usage` | object | Có |  |
| `metadata` | object hoặc null | Có |  |
| `completed_at` | integer hoặc null | Có |  |
| `expires_at` | integer hoặc null | Có | Dấu thời gian Unix mà sau đó kết quả bị xóa. |

**file: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `name` | string hoặc null | Không |  |
| `bytes` | integer hoặc null | Không |  |
| `format` | string hoặc null | Không |  |

**summary (ImageSummary): các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `level` | một trong `"L0"`, `"L1"`, `"L2"`, `"L3"`, `"L4"`, `"L5"` | Có | Mức độ rủi ro, từ L0 đến L5. |
| `assessment` | một trong `"authentic_untouched"`, `"authentic_locally_edited"`, `"ai_generated"`, `"undetermined"` | Có |  |
| `action` | một trong `"accept"`, `"review"`, `"reject"`, `"resubmit"` | Có |  |
| `ai` | một trong `"labelled"`, `"very_likely"`, `"suspected"`, `"undecided"`, `"low"`, `"very_low"`, `"not_evaluated"` | Có | Phát hiện về nội dung do AI tạo ra. |
| `edit` | một trong `"detected"`, `"suspected"`, `"suspected_record"`, `"review"`, `"generative"`, `"minor"`, `"none"`, `"not_applicable"`, `"not_evaluated"` | Có | Phát hiện về chỉnh sửa cục bộ. |

**summary (DocumentSummary): các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `kind` | `"docpro"` | Có |  |
| `level` | một trong `"L0"`, `"L1"`, `"L2"`, `"L3"`, `"L4"`, `"L5"` | Có | Mức độ rủi ro, từ L0 đến L5. |
| `action` | một trong `"accept"`, `"note"`, `"review"`, `"reject"`, `"resubmit"` | Có | note: hãy đố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. |
| `reason` | string hoặc null | Có | Phát hiện hoặc điều kiện đằng sau mức này, ví dụ clean hoặc incomplete, hoặc mã của một phát hiện. |
| `findings` | mảng string | Có | Mã của các phát hiện quan trọng. |
| `pages` | integer | Có | Số trang trong tài liệu. |
| `images` | integer | Có | Số ảnh nhúng đã được kiểm tra. |
| `text` | một trong `"ai_generated"`, `"mixed"`, `"human"`, `"inconclusive"`, `null` | Có | Kết luận về văn bản của tài liệu, hoặc null nếu văn bản không được đánh giá. |
| `strong` | `true` | Không | Xuất hiện khi một phát hiện được liệt kê là mạnh. |

**result: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `report` | `ImageReport` hoặc `DocumentReport` | Không | Báo cáo đầy đủ. report.schema là fileverity.report/1 cho ảnh và fileverity.docpro/1 cho tài liệu. |
| `stamped_at` | integer hoặc null | Không | 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. |

**report (ImageReport): các trường**

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

**issuer: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `name` | string | Không |  |
| `operator` | string | Không |  |
| `verify` | string | Không | Trang xác minh công khai của báo cáo. |

**file: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `name` | string hoặc null | Không |  |
| `sha256` | string | Không | Giá trị băm SHA-256 của tệp đã kiểm tra, ở dạng hex. |
| `bytes` | integer | Không |  |
| `width` | integer | Không | Chiều rộng tính bằng điểm ảnh như khi hiển thị. |
| `height` | integer | Không | Chiều cao tính bằng điểm ảnh như khi hiển thị. |
| `format` | string | Không |  |

**pro: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `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"`, `"review"`, `"reject"`, `"resubmit"` | Không |  |
| `assessment` | một trong `"authentic_untouched"`, `"authentic_locally_edited"`, `"ai_generated"`, `"undetermined"` | Không |  |
| `reason` | string hoặc null | Không |  |

**questions: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `ai` | object | Không |  |
| `edit` | object | Không |  |
| `source` | object | Không |  |

**ai: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `key` | một trong `"labelled"`, `"very_likely"`, `"suspected"`, `"undecided"`, `"low"`, `"very_low"`, `"not_evaluated"` | Không |  |
| `basis` | một trong `"verified"`, `"detected"`, `"declared"`, `null` | Không | Cơ sở của câu trả lời. |
| `strength` | một trong `"strong"`, `"moderate"`, `"limited"`, `null` | Không | Bằng chứng ủng hộ câu trả lời mạnh đến đâu. |
| `likelihood` | integer hoặc null | Không | Khả năng nội dung do AI tạo ra, từ 0 đến 100 với bước nhảy 5, hoặc null. |

**edit: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `key` | một trong `"detected"`, `"suspected"`, `"suspected_record"`, `"review"`, `"generative"`, `"minor"`, `"none"`, `"not_applicable"`, `"not_evaluated"` | Không |  |
| `basis` | một trong `"verified"`, `"detected"`, `"declared"`, `null` | Không | Cơ sở của câu trả lời. |
| `strength` | một trong `"strong"`, `"moderate"`, `"limited"`, `null` | Không | Bằng chứng ủng hộ câu trả lời mạnh đến đâu. |
| `regions` | integer | Không | Số vùng được đánh dấu. |

**source: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `key` | string | Không |  |
| `basis` | một trong `"verified"`, `"detected"`, `"declared"`, `null` | Không | Cơ sở của câu trả lời. |
| `strength` | một trong `"strong"`, `"moderate"`, `"limited"`, `null` | Không | Bằng chứng ủng hộ câu trả lời mạnh đến đâu. |
| `signer` | string hoặc null | Không |  |
| `aiClaim` | boolean | Không | Liệu bản ghi của chính tệp có khai là do AI tạo ra hay không. |

**generator: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `name` | string | Không |  |
| `basis` | string | Không | Cách xác định công cụ tạo ảnh. |

**regions: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `id` | string | Không |  |
| `x` | integer | Không |  |
| `y` | integer | Không |  |
| `w` | integer | Không |  |
| `h` | integer | Không |  |
| `strength` | một trong `"high"`, `"medium"` | Không |  |

**provenance: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `credentials` | một trong `"valid"`, `"unverified"`, `"issues"`, `"invalid"`, `"removed"`, `"none"` | Không | Trạng thái của Content Credentials. |
| `signer` | string hoặc null | Không |  |
| `software` | mảng string | Không | Phần mềm được nêu trong bản ghi của tệp. |
| `camera` | string hoặc null | Không |  |
| `captured` | string hoặc null | Không | Thời điểm chụp được ghi trong tệp, nếu có. |

**report (DocumentReport): các trường**

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

**issuer: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `name` | string | Không |  |
| `operator` | string | Không |  |
| `verify` | string | Không | Trang xác minh công khai của báo cáo. |

**file: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `name` | string hoặc null | Không |  |
| `sha256` | string | Không | Giá trị băm SHA-256 của tệp đã kiểm tra, ở dạng hex. |
| `bytes` | integer | Không |  |
| `format` | string | Không |  |
| `pages` | integer | Không |  |
| `textLayer` | một trong `"present"`, `"partial"`, `"absent"` | Không | Liệu tài liệu có lớp văn bản hay không. |

**findings: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `id` | string | Không |  |
| `basis` | một trong `"verified"`, `"detected"`, `"declared"` | Không |  |
| `strength` | một trong `"strong"`, `"moderate"`, `"limited"` | Không |  |
| `material` | boolean | Không | Liệu phát hiện có được tính vào mức hay không. |
| `pages` | mảng integer | Không |  |
| `images` | mảng integer | Không |  |

**text: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `status` | một trong `"evaluated"`, `"insufficient_text"`, `"unsupported_language"`, `"no_text"` | Không |  |
| `verdict` | một trong `"ai_generated"`, `"mixed"`, `"human"`, `"inconclusive"` | Không | Xuất hiện khi status là evaluated. |
| `words` | integer | Không |  |
| `languages` | mảng string | Không |  |
| `passages` | integer | Không | Số đoạn được đánh dấu. |

**images: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `n` | integer | Không |  |
| `pages` | mảng integer | Không |  |
| `kind` | một trong `"photo"`, `"graphic"` | Không |  |
| `width` | integer | Không |  |
| `height` | integer | Không |  |
| `level` | một trong `"L0"`, `"L1"`, `"L2"`, `"L3"`, `"L4"`, `"L5"`, `null` | Không |  |
| `assessment` | một trong `"authentic_untouched"`, `"authentic_locally_edited"`, `"ai_generated"`, `"undetermined"`, `null` | Không |  |
| `ai` | một trong `"labelled"`, `"very_likely"`, `"suspected"`, `"undecided"`, `"low"`, `"very_low"`, `"not_evaluated"`, `null` | Không |  |
| `edit` | một trong `"detected"`, `"suspected"`, `"suspected_record"`, `"review"`, `"generative"`, `"minor"`, `"none"`, `"not_applicable"`, `"not_evaluated"`, `null` | Không |  |

**structure: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `revisions` | integer hoặc null | Không |  |
| `changedPages` | mảng integer | Không |  |
| `addedPages` | integer | Không |  |
| `signatures` | integer | Không |  |

**provenance: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `credentials` | string | Không | Trạng thái của Content Credentials. |
| `signer` | string hoặc null | Không |  |
| `aiClaim` | boolean | Không | Liệu bản ghi của chính tệp có khai là do AI tạo ra hay không. |
| `software` | mảng string | Không |  |
| `created` | string hoặc null | Không |  |
| `modified` | string hoặc null | Không |  |
| `revisions` | integer hoặc null | Không |  |
| `signed` | boolean hoặc null | Không |  |

**error: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `code` | một trong `"invalid_json"`, `"missing_parameter"`, `"invalid_parameter"`, `"text_too_short"`, `"text_too_long"`, `"unsupported_media_type"`, `"unsupported_language"`, `"file_not_found"`, `"unsupported_file"`, `"file_too_large"`, `"too_many_pixels"`, `"too_many_pages"`, `"document_too_long"`, `"invalid_file"`, `"password_required"`, `"wrong_password"`, `"not_examinable"`, `"missing_api_key"`, `"invalid_api_key"`, `"insufficient_balance"`, `"spend_limit_reached"`, `"not_found"`, `"model_not_found"`, `"not_cancelable"`, `"canceled"`, `"idempotency_mismatch"`, `"idempotency_in_progress"`, `"pending_files_limit"`, `"rate_limited"`, `"internal_error"`, `"analysis_failed"`, `"service_unavailable"` | Không |  |
| `message` | string | Không |  |

**progress: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `stage` | một trong `"queued"`, `"reading"`, `"analyzing"`, `"reporting"` | Không |  |
| `done` | integer | Không | Số đơn vị đã hoàn thành trong giai đoạn hiện tại, nếu biết; nếu không thì là 0. |
| `total` | integer | Không | Số đơn vị trong giai đoạn hiện tại, nếu biết; nếu không thì là 0. |
| `position` | integer | Không | Vị trí trong hàng đợi khi giai đoạn là queued. |

**usage: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `amount` | integer | Không | Số tiền bị 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` | `"usd"` | Không |  |
| `funding` | một trong `"trial"`, `"balance"`, `null` | Không |  |

#### Mã lỗi

| Mã lỗi | Trạng thái |
| --- | --- |
| `invalid_json` | 400 |
| `missing_parameter` | 400 |
| `unsupported_media_type` | 415 |
| `model_not_found` | 404 |
| `file_not_found` | 400 |
| `unsupported_file` | 415 |
| `invalid_file` | 422 |
| `file_too_large` | 413 |
| `too_many_pixels` | 413 |
| `too_many_pages` | 413 |
| `document_too_long` | 413 |
| `password_required` | 422 |
| `wrong_password` | 422 |
| `not_examinable` | 422 |
| `insufficient_balance` | 402 |
| `spend_limit_reached` | 402 |
| `service_unavailable` | 503 |
| `analysis_failed` | 502 |
| `invalid_parameter` | 400 |
| `idempotency_mismatch` | 409 |
| `idempotency_in_progress` | 409 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Ví dụ

**Yêu cầu: cURL**

```bash
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_8Hk2pQ4vN9sL1xR7cW3mY6zB"}'
```

**Phản hồi**

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

### Liệt kê các lượt phân tích

`GET` `https://api.fileverity.com/v1/analyses`

Liệt kê các lượt phân tích ảnh và tài liệu của không gian làm việc của bạn, mới nhất trước. Khóa thử nghiệm luôn nhận danh sách trống.

#### Tham số

| Tên | Vị trí | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- | --- |
| `limit` | query | integer | Không | Mặc định `20`. Tối thiểu 1. Tối đa 100. |
| `starting_after` | query | string | Không | Con trỏ (cursor): next_cursor của trang trước. |
| `type` | query | một trong `"image"`, `"document"` | Không |  |

#### Phản hồi

| Trạng thái | Mô tả | Nội dung |
| --- | --- | --- |
| 200 | Một trang các lượt phân tích. | `AnalysisList` |
| 400 | Yêu cầu không hợp lệ. Mã lỗi: invalid_parameter. | `Error` |
| 401 | Thiếu khóa API hoặc khóa API không hợp lệ. Mã lỗi: missing_api_key, invalid_api_key. | `Error` |
| 429 | Quá nhiều yêu cầu. Mã lỗi: rate_limited. | `Error` |
| 500 | Lỗi nội bộ; không bị tính phí. Mã lỗi: internal_error. | `Error` |

#### Phản hồi 200: AnalysisList

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `object` | `"list"` | Có |  |
| `data` | mảng `Analysis` | Có |  |
| `has_more` | boolean | Có |  |
| `next_cursor` | string hoặc null | Có | Truyền vào starting_after để lấy trang tiếp theo. |

**data: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `id` | string | Có |  |
| `object` | `"analysis"` | Có |  |
| `created` | integer | Có | Dấu thời gian Unix. |
| `model` | string | Có | Snapshot đã tạo ra kết quả. |
| `livemode` | boolean | Có |  |
| `status` | một trong `"processing"`, `"succeeded"`, `"failed"`, `"canceled"` | Có |  |
| `file` | object | Có |  |
| `report_id` | string hoặc null | Có | Mã báo cáo có thể xác minh, FV-XXXX-XXXX-XXXX. |
| `report_url` | string hoặc null | Có | Trang xác minh công khai của báo cáo. |
| `summary` | `ImageSummary` hoặc `DocumentSummary` hoặc null | Có | Kết luận ngắn gọn, ổn định: ImageSummary cho ảnh, DocumentSummary cho tài liệu, null cho đến khi lượt phân tích thành công. |
| `result` | object hoặc null | Có | Xuất hiện khi status là succeeded và cho đến khi kết quả hết hạn. |
| `error` | object hoặc null | Có |  |
| `progress` | object hoặc null | Có |  |
| `usage` | object | Có |  |
| `metadata` | object hoặc null | Có |  |
| `completed_at` | integer hoặc null | Có |  |
| `expires_at` | integer hoặc null | Có | Dấu thời gian Unix mà sau đó kết quả bị xóa. |

**file: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `name` | string hoặc null | Không |  |
| `bytes` | integer hoặc null | Không |  |
| `format` | string hoặc null | Không |  |

**result: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `report` | `ImageReport` hoặc `DocumentReport` | Không | Báo cáo đầy đủ. report.schema là fileverity.report/1 cho ảnh và fileverity.docpro/1 cho tài liệu. |
| `stamped_at` | integer hoặc null | Không | 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. |

**error: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `code` | một trong `"invalid_json"`, `"missing_parameter"`, `"invalid_parameter"`, `"text_too_short"`, `"text_too_long"`, `"unsupported_media_type"`, `"unsupported_language"`, `"file_not_found"`, `"unsupported_file"`, `"file_too_large"`, `"too_many_pixels"`, `"too_many_pages"`, `"document_too_long"`, `"invalid_file"`, `"password_required"`, `"wrong_password"`, `"not_examinable"`, `"missing_api_key"`, `"invalid_api_key"`, `"insufficient_balance"`, `"spend_limit_reached"`, `"not_found"`, `"model_not_found"`, `"not_cancelable"`, `"canceled"`, `"idempotency_mismatch"`, `"idempotency_in_progress"`, `"pending_files_limit"`, `"rate_limited"`, `"internal_error"`, `"analysis_failed"`, `"service_unavailable"` | Không |  |
| `message` | string | Không |  |

**progress: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `stage` | một trong `"queued"`, `"reading"`, `"analyzing"`, `"reporting"` | Không |  |
| `done` | integer | Không | Số đơn vị đã hoàn thành trong giai đoạn hiện tại, nếu biết; nếu không thì là 0. |
| `total` | integer | Không | Số đơn vị trong giai đoạn hiện tại, nếu biết; nếu không thì là 0. |
| `position` | integer | Không | Vị trí trong hàng đợi khi giai đoạn là queued. |

**usage: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `amount` | integer | Không | Số tiền bị 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` | `"usd"` | Không |  |
| `funding` | một trong `"trial"`, `"balance"`, `null` | Không |  |

#### Mã lỗi

| Mã lỗi | Trạng thái |
| --- | --- |
| `invalid_parameter` | 400 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Ví dụ

**Yêu cầu: cURL**

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

**Phản hồi**

```json
{
  "object": "list",
  "data": [
    {
      "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
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

### Lấy thông tin một lượt phân tích

`GET` `https://api.fileverity.com/v1/analyses/{id}`

Trả về lượt phân tích, kèm kết quả khi lượt phân tích đã thành công và cho đến khi kết quả hết hạn.

#### Tham số

| Tên | Vị trí | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- | --- |
| `id` | path | string | Có | Mã lượt phân tích. |

#### Phản hồi

| Trạng thái | Mô tả | Nội dung |
| --- | --- | --- |
| 200 | Lượt phân tích. | `Analysis` |
| 401 | Thiếu khóa API hoặc khóa API không hợp lệ. Mã lỗi: missing_api_key, invalid_api_key. | `Error` |
| 404 | Không tìm thấy tài nguyên. Mã lỗi: not_found. | `Error` |
| 429 | Quá nhiều yêu cầu. Mã lỗi: rate_limited. | `Error` |
| 500 | Lỗi nội bộ; không bị tính phí. Mã lỗi: internal_error. | `Error` |

#### Phản hồi 200: Analysis

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `id` | string | Có |  |
| `object` | `"analysis"` | Có |  |
| `created` | integer | Có | Dấu thời gian Unix. |
| `model` | string | Có | Snapshot đã tạo ra kết quả. |
| `livemode` | boolean | Có |  |
| `status` | một trong `"processing"`, `"succeeded"`, `"failed"`, `"canceled"` | Có |  |
| `file` | object | Có |  |
| `report_id` | string hoặc null | Có | Mã báo cáo có thể xác minh, FV-XXXX-XXXX-XXXX. |
| `report_url` | string hoặc null | Có | Trang xác minh công khai của báo cáo. |
| `summary` | `ImageSummary` hoặc `DocumentSummary` hoặc null | Có | Kết luận ngắn gọn, ổn định: ImageSummary cho ảnh, DocumentSummary cho tài liệu, null cho đến khi lượt phân tích thành công. |
| `result` | object hoặc null | Có | Xuất hiện khi status là succeeded và cho đến khi kết quả hết hạn. |
| `error` | object hoặc null | Có |  |
| `progress` | object hoặc null | Có |  |
| `usage` | object | Có |  |
| `metadata` | object hoặc null | Có |  |
| `completed_at` | integer hoặc null | Có |  |
| `expires_at` | integer hoặc null | Có | Dấu thời gian Unix mà sau đó kết quả bị xóa. |

**file: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `name` | string hoặc null | Không |  |
| `bytes` | integer hoặc null | Không |  |
| `format` | string hoặc null | Không |  |

**result: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `report` | `ImageReport` hoặc `DocumentReport` | Không | Báo cáo đầy đủ. report.schema là fileverity.report/1 cho ảnh và fileverity.docpro/1 cho tài liệu. |
| `stamped_at` | integer hoặc null | Không | 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. |

**error: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `code` | một trong `"invalid_json"`, `"missing_parameter"`, `"invalid_parameter"`, `"text_too_short"`, `"text_too_long"`, `"unsupported_media_type"`, `"unsupported_language"`, `"file_not_found"`, `"unsupported_file"`, `"file_too_large"`, `"too_many_pixels"`, `"too_many_pages"`, `"document_too_long"`, `"invalid_file"`, `"password_required"`, `"wrong_password"`, `"not_examinable"`, `"missing_api_key"`, `"invalid_api_key"`, `"insufficient_balance"`, `"spend_limit_reached"`, `"not_found"`, `"model_not_found"`, `"not_cancelable"`, `"canceled"`, `"idempotency_mismatch"`, `"idempotency_in_progress"`, `"pending_files_limit"`, `"rate_limited"`, `"internal_error"`, `"analysis_failed"`, `"service_unavailable"` | Không |  |
| `message` | string | Không |  |

**progress: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `stage` | một trong `"queued"`, `"reading"`, `"analyzing"`, `"reporting"` | Không |  |
| `done` | integer | Không | Số đơn vị đã hoàn thành trong giai đoạn hiện tại, nếu biết; nếu không thì là 0. |
| `total` | integer | Không | Số đơn vị trong giai đoạn hiện tại, nếu biết; nếu không thì là 0. |
| `position` | integer | Không | Vị trí trong hàng đợi khi giai đoạn là queued. |

**usage: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `amount` | integer | Không | Số tiền bị 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` | `"usd"` | Không |  |
| `funding` | một trong `"trial"`, `"balance"`, `null` | Không |  |

#### Mã lỗi

| Mã lỗi | Trạng thái |
| --- | --- |
| `not_found` | 404 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Ví dụ

**Yêu cầu: cURL**

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

**Phản hồi**

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

### Hủy một lượt phân tích

`POST` `https://api.fileverity.com/v1/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 tạm giữ của lượt đó. Các lượt phân tích ảnh không thể hủy sau khi đã được tạo.

#### Tham số

| Tên | Vị trí | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- | --- |
| `id` | path | string | Có | Mã lượt phân tích. |
| `Idempotency-Key` | header | string | Không | Khóa duy nhất tối đa 255 ký tự. Gửi lại yêu cầu với cùng khóa và cùng nội dung trong vòng 24 giờ sẽ trả về phản hồi đầu tiên kèm header idempotent-replayed: true; cùng khóa nhưng nội dung khác trả về 409. |

#### Phản hồi

| Trạng thái | Mô tả | Nội dung |
| --- | --- | --- |
| 200 | Lượt phân tích đã bị hủy. | `Analysis` |
| 400 | Yêu cầu không hợp lệ. Mã lỗi: invalid_parameter. | `Error` |
| 401 | Thiếu khóa API hoặc khóa API không hợp lệ. Mã lỗi: missing_api_key, invalid_api_key. | `Error` |
| 404 | Không tìm thấy tài nguyên. Mã lỗi: not_found. | `Error` |
| 409 | Xung đột với trạng thái hiện tại. Mã lỗi: not_cancelable, idempotency_mismatch, idempotency_in_progress. | `Error` |
| 429 | Quá nhiều yêu cầu. Mã lỗi: rate_limited. | `Error` |
| 500 | Lỗi nội bộ; không bị tính phí. Mã lỗi: internal_error. | `Error` |

#### Phản hồi 200: Analysis

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `id` | string | Có |  |
| `object` | `"analysis"` | Có |  |
| `created` | integer | Có | Dấu thời gian Unix. |
| `model` | string | Có | Snapshot đã tạo ra kết quả. |
| `livemode` | boolean | Có |  |
| `status` | một trong `"processing"`, `"succeeded"`, `"failed"`, `"canceled"` | Có |  |
| `file` | object | Có |  |
| `report_id` | string hoặc null | Có | Mã báo cáo có thể xác minh, FV-XXXX-XXXX-XXXX. |
| `report_url` | string hoặc null | Có | Trang xác minh công khai của báo cáo. |
| `summary` | `ImageSummary` hoặc `DocumentSummary` hoặc null | Có | Kết luận ngắn gọn, ổn định: ImageSummary cho ảnh, DocumentSummary cho tài liệu, null cho đến khi lượt phân tích thành công. |
| `result` | object hoặc null | Có | Xuất hiện khi status là succeeded và cho đến khi kết quả hết hạn. |
| `error` | object hoặc null | Có |  |
| `progress` | object hoặc null | Có |  |
| `usage` | object | Có |  |
| `metadata` | object hoặc null | Có |  |
| `completed_at` | integer hoặc null | Có |  |
| `expires_at` | integer hoặc null | Có | Dấu thời gian Unix mà sau đó kết quả bị xóa. |

**file: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `name` | string hoặc null | Không |  |
| `bytes` | integer hoặc null | Không |  |
| `format` | string hoặc null | Không |  |

**result: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `report` | `ImageReport` hoặc `DocumentReport` | Không | Báo cáo đầy đủ. report.schema là fileverity.report/1 cho ảnh và fileverity.docpro/1 cho tài liệu. |
| `stamped_at` | integer hoặc null | Không | 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. |

**error: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `code` | một trong `"invalid_json"`, `"missing_parameter"`, `"invalid_parameter"`, `"text_too_short"`, `"text_too_long"`, `"unsupported_media_type"`, `"unsupported_language"`, `"file_not_found"`, `"unsupported_file"`, `"file_too_large"`, `"too_many_pixels"`, `"too_many_pages"`, `"document_too_long"`, `"invalid_file"`, `"password_required"`, `"wrong_password"`, `"not_examinable"`, `"missing_api_key"`, `"invalid_api_key"`, `"insufficient_balance"`, `"spend_limit_reached"`, `"not_found"`, `"model_not_found"`, `"not_cancelable"`, `"canceled"`, `"idempotency_mismatch"`, `"idempotency_in_progress"`, `"pending_files_limit"`, `"rate_limited"`, `"internal_error"`, `"analysis_failed"`, `"service_unavailable"` | Không |  |
| `message` | string | Không |  |

**progress: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `stage` | một trong `"queued"`, `"reading"`, `"analyzing"`, `"reporting"` | Không |  |
| `done` | integer | Không | Số đơn vị đã hoàn thành trong giai đoạn hiện tại, nếu biết; nếu không thì là 0. |
| `total` | integer | Không | Số đơn vị trong giai đoạn hiện tại, nếu biết; nếu không thì là 0. |
| `position` | integer | Không | Vị trí trong hàng đợi khi giai đoạn là queued. |

**usage: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `amount` | integer | Không | Số tiền bị 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` | `"usd"` | Không |  |
| `funding` | một trong `"trial"`, `"balance"`, `null` | Không |  |

#### Mã lỗi

| Mã lỗi | Trạng thái |
| --- | --- |
| `not_found` | 404 |
| `not_cancelable` | 409 |
| `invalid_parameter` | 400 |
| `idempotency_mismatch` | 409 |
| `idempotency_in_progress` | 409 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Ví dụ

**Yêu cầu: cURL**

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

**Phản hồi**

```json
{
  "id": "an_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "analysis",
  "created": 1793700120,
  "model": "fvimg-2-2026-10-30",
  "livemode": true,
  "status": "canceled",
  "file": {
    "name": "claim-photo.jpg",
    "bytes": 2481920,
    "format": "jpeg"
  },
  "report_id": null,
  "report_url": null,
  "summary": null,
  "result": null,
  "error": {
    "code": "canceled",
    "message": "The analysis was canceled. You were not charged."
  },
  "progress": null,
  "usage": {
    "amount": 0,
    "currency": "usd",
    "funding": null
  },
  "metadata": null,
  "completed_at": 1793700135,
  "expires_at": null
}
```

### Tải xuống báo cáo PDF

`GET` `https://api.fileverity.com/v1/analyses/{id}/report.pdf`

Trả về 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 trong khi kết quả của nó còn được lưu. Khóa thử nghiệm nhận 404. Bằng chứng của tài liệu như ảnh các trang có sẵn trong 3 giờ sau lượt phân tích; sau đó PDF không còn chứa phần này, được báo hiệu bằng x-evidence-included: false.

#### Tham số

| Tên | Vị trí | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- | --- |
| `id` | path | string | Có | Mã lượt phân tích. |
| `locale` | query | một trong `"en"`, `"fr"`, `"de"`, `"es"`, `"zh"`, `"vi"`, `"ar"` | Không | Mặc định `"en"`. |

#### Phản hồi

| Trạng thái | Mô tả | Nội dung |
| --- | --- | --- |
| 200 | Báo cáo PDF. | Tệp PDF |
| 400 | Yêu cầu không hợp lệ. Mã lỗi: invalid_parameter. | `Error` |
| 401 | Thiếu khóa API hoặc khóa API không hợp lệ. Mã lỗi: missing_api_key, invalid_api_key. | `Error` |
| 404 | Không tìm thấy tài nguyên. Mã lỗi: not_found. | `Error` |
| 429 | Quá nhiều yêu cầu. Mã lỗi: rate_limited. | `Error` |
| 500 | Lỗi nội bộ; không bị tính phí. Mã lỗi: internal_error. | `Error` |

#### Mã lỗi

| Mã lỗi | Trạng thái |
| --- | --- |
| `invalid_parameter` | 400 |
| `not_found` | 404 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Ví dụ

**Yêu cầu: 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
```

## Mô hình

### Liệt kê các mô hình

`GET` `https://api.fileverity.com/v1/models`

Liệt kê các mô hình khả dụng với khóa API của bạn.

#### Phản hồi

| Trạng thái | Mô tả | Nội dung |
| --- | --- | --- |
| 200 | Các mô hình khả dụng. | `ModelList` |
| 401 | Thiếu khóa API hoặc khóa API không hợp lệ. Mã lỗi: missing_api_key, invalid_api_key. | `Error` |
| 429 | Quá nhiều yêu cầu. Mã lỗi: rate_limited. | `Error` |
| 500 | Lỗi nội bộ; không bị tính phí. Mã lỗi: internal_error. | `Error` |

#### Phản hồi 200: ModelList

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `object` | `"list"` | Có |  |
| `data` | mảng `Model` | Có |  |

**data: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `id` | string | Có |  |
| `object` | `"model"` | Có |  |
| `created` | integer | Có | Dấu thời gian Unix của snapshot hiện tại. |
| `owned_by` | string | Có |  |
| `name` | string | Có |  |
| `type` | một trong `"image"`, `"document"`, `"text"` | Có |  |
| `description` | string | Có |  |
| `snapshot` | string | Có | Snapshot có ghi ngày mà mã mô hình hiện đang trỏ tới. |
| `status` | một trong `"available"`, `"preview"`, `"deprecated"` | Có |  |
| `input` | object | Có | Đầu vào được chấp nhận. Với tệp, đó là các định dạng và giới hạn kích thước; với văn bản, đó là các ngôn ngữ và giới hạn độ dài. |
| `output` | object | Có |  |
| `pricing` | object | Có |  |

**input: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `formats` | mảng string | Không |  |
| `max_bytes` | integer | Không |  |
| `max_megapixels` | integer | Không |  |
| `max_pages` | integer | Không |  |
| `languages` | mảng string | Không |  |
| `min_words` | integer | Không |  |
| `max_characters` | integer | Không |  |

**output: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `schema` | string | Có | Schema của báo cáo trong kết quả phân tích. |

**pricing: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `currency` | `"usd"` | Có |  |
| `unit` | string | Có |  |
| `unit_amount` | integer | Có | Giá mỗi đơn vị, tính bằng cent. |

#### Mã lỗi

| Mã lỗi | Trạng thái |
| --- | --- |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Ví dụ

**Yêu cầu: cURL**

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

**Phản hồi**

```json
{
  "object": "list",
  "data": [
    {
      "id": "fvimg-2",
      "object": "model",
      "created": 1793318400,
      "owned_by": "fileverity",
      "name": "FVIMG V2",
      "type": "image",
      "description": "Image authenticity analysis. Detects AI generation and local edits, checks content credentials and metadata, and returns a verifiable report.",
      "snapshot": "fvimg-2-2026-10-30",
      "status": "available",
      "input": {
        "formats": [
          "jpeg",
          "png",
          "webp"
        ],
        "max_bytes": 10485760,
        "max_megapixels": 40
      },
      "output": {
        "schema": "fileverity.report/1"
      },
      "pricing": {
        "currency": "usd",
        "unit": "image",
        "unit_amount": 199
      }
    },
    {
      "id": "fvdoc-3",
      "object": "model",
      "created": 1793664000,
      "owned_by": "fileverity",
      "name": "FVDOC V3",
      "type": "document",
      "description": "Document fraud analysis. Evaluates AI-written text, embedded photos, edit history and signatures, and returns a verifiable report.",
      "snapshot": "fvdoc-3-2026-11-03",
      "status": "available",
      "input": {
        "formats": [
          "pdf",
          "docx",
          "doc",
          "rtf",
          "odt",
          "pptx",
          "txt"
        ],
        "max_bytes": 52428800,
        "max_pages": 100
      },
      "output": {
        "schema": "fileverity.docpro/1"
      },
      "pricing": {
        "currency": "usd",
        "unit": "document",
        "unit_amount": 599
      }
    },
    {
      "id": "fvdoc-3-text",
      "object": "model",
      "created": 1793664000,
      "owned_by": "fileverity",
      "name": "FVDOC V3 Text",
      "type": "text",
      "description": "AI-written text detection. Classifies plain text as AI-written, partly AI-written or human-written and marks the AI-written passages.",
      "snapshot": "fvdoc-3-text-2026-11-03",
      "status": "available",
      "input": {
        "languages": [
          "en",
          "fr",
          "de",
          "es",
          "zh"
        ],
        "min_words": 100,
        "max_characters": 100000
      },
      "output": {
        "schema": "fileverity.text-detection/1"
      },
      "pricing": {
        "currency": "usd",
        "unit": "1000_characters",
        "unit_amount": 14
      }
    }
  ]
}
```

### Lấy thông tin một mô hình

`GET` `https://api.fileverity.com/v1/models/{model}`

Lấy thông tin một mô hình theo mã mô hình hoặc mã snapshot của nó.

#### Tham số

| Tên | Vị trí | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- | --- |
| `model` | path | string | Có | Mã mô hình hoặc mã snapshot. |

#### Phản hồi

| Trạng thái | Mô tả | Nội dung |
| --- | --- | --- |
| 200 | Mô hình. | `Model` |
| 401 | Thiếu khóa API hoặc khóa API không hợp lệ. Mã lỗi: missing_api_key, invalid_api_key. | `Error` |
| 404 | Không tìm thấy tài nguyên. Mã lỗi: model_not_found. | `Error` |
| 429 | Quá nhiều yêu cầu. Mã lỗi: rate_limited. | `Error` |
| 500 | Lỗi nội bộ; không bị tính phí. Mã lỗi: internal_error. | `Error` |

#### Phản hồi 200: Model

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `id` | string | Có |  |
| `object` | `"model"` | Có |  |
| `created` | integer | Có | Dấu thời gian Unix của snapshot hiện tại. |
| `owned_by` | string | Có |  |
| `name` | string | Có |  |
| `type` | một trong `"image"`, `"document"`, `"text"` | Có |  |
| `description` | string | Có |  |
| `snapshot` | string | Có | Snapshot có ghi ngày mà mã mô hình hiện đang trỏ tới. |
| `status` | một trong `"available"`, `"preview"`, `"deprecated"` | Có |  |
| `input` | object | Có | Đầu vào được chấp nhận. Với tệp, đó là các định dạng và giới hạn kích thước; với văn bản, đó là các ngôn ngữ và giới hạn độ dài. |
| `output` | object | Có |  |
| `pricing` | object | Có |  |

**input: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `formats` | mảng string | Không |  |
| `max_bytes` | integer | Không |  |
| `max_megapixels` | integer | Không |  |
| `max_pages` | integer | Không |  |
| `languages` | mảng string | Không |  |
| `min_words` | integer | Không |  |
| `max_characters` | integer | Không |  |

**output: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `schema` | string | Có | Schema của báo cáo trong kết quả phân tích. |

**pricing: các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `currency` | `"usd"` | Có |  |
| `unit` | string | Có |  |
| `unit_amount` | integer | Có | Giá mỗi đơn vị, tính bằng cent. |

#### Mã lỗi

| Mã lỗi | Trạng thái |
| --- | --- |
| `model_not_found` | 404 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Ví dụ

**Yêu cầu: cURL**

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

**Phản hồi**

```json
{
  "id": "fvimg-2",
  "object": "model",
  "created": 1793318400,
  "owned_by": "fileverity",
  "name": "FVIMG V2",
  "type": "image",
  "description": "Image authenticity analysis. Detects AI generation and local edits, checks content credentials and metadata, and returns a verifiable report.",
  "snapshot": "fvimg-2-2026-10-30",
  "status": "available",
  "input": {
    "formats": [
      "jpeg",
      "png",
      "webp"
    ],
    "max_bytes": 10485760,
    "max_megapixels": 40
  },
  "output": {
    "schema": "fileverity.report/1"
  },
  "pricing": {
    "currency": "usd",
    "unit": "image",
    "unit_amount": 199
  }
}
```

## Sự kiện webhook

Fileverity gửi các sự kiện này tới các endpoint webhook của bạn. Quy tắc xác minh và gửi nằm trong [Webhook](https://fileverity.com/vi/docs/webhooks.md).

### Sự kiện analysis.completed

Được gửi tới các endpoint webhook của bạn theo đặc tả Standard Webhooks: các header webhook-id, webhook-timestamp và webhook-signature (v1,<base64 của HMAC-SHA256 trên id.timestamp.body>, dùng phần base64 của khóa bí mật whsec_ làm khóa). Hãy phản hồi bằng bất kỳ mã 2xx nào trong vòng 10 giây; các lần thất bại được thử lại với độ trễ tăng dần theo cấp số nhân (exponential backoff) trong 3 ngày.

#### Nội dung yêu cầu: application/json, bắt buộc

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `id` | string | Có | Cũng được gửi dưới dạng header webhook-id; dùng để loại bỏ các yêu cầu thử lại trùng lặp. |
| `object` | `"event"` | Có |  |
| `type` | một trong `"analysis.completed"`, `"analysis.failed"`, `"balance.low"` | Có |  |
| `created` | integer | Có | Dấu thời gian Unix. |
| `data` | `Analysis` hoặc `BalanceLow` | Có | Các sự kiện analysis.* chứa cùng đối tượng với GET /analyses/{id}, trong đó result luôn là null; hãy lấy kết quả bằng endpoint đó. Các sự kiện balance.low chứa số dư và ngưỡng, tính bằng cent. |

**data (BalanceLow): các trường**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `balance` | integer | Có | Số dư tính bằng cent. |
| `threshold` | integer | Có | Ngưỡng cảnh báo tính bằng cent. |

### Sự kiện analysis.failed

Được gửi tới các endpoint webhook của bạn theo đặc tả Standard Webhooks: các header webhook-id, webhook-timestamp và webhook-signature (v1,<base64 của HMAC-SHA256 trên id.timestamp.body>, dùng phần base64 của khóa bí mật whsec_ làm khóa). Hãy phản hồi bằng bất kỳ mã 2xx nào trong vòng 10 giây; các lần thất bại được thử lại với độ trễ tăng dần theo cấp số nhân (exponential backoff) trong 3 ngày.

#### Nội dung yêu cầu: application/json, bắt buộc

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `id` | string | Có | Cũng được gửi dưới dạng header webhook-id; dùng để loại bỏ các yêu cầu thử lại trùng lặp. |
| `object` | `"event"` | Có |  |
| `type` | một trong `"analysis.completed"`, `"analysis.failed"`, `"balance.low"` | Có |  |
| `created` | integer | Có | Dấu thời gian Unix. |
| `data` | `Analysis` hoặc `BalanceLow` | Có | Các sự kiện analysis.* chứa cùng đối tượng với GET /analyses/{id}, trong đó result luôn là null; hãy lấy kết quả bằng endpoint đó. Các sự kiện balance.low chứa số dư và ngưỡng, tính bằng cent. |

### Sự kiện balance.low

Được gửi tới các endpoint webhook của bạn theo đặc tả Standard Webhooks: các header webhook-id, webhook-timestamp và webhook-signature (v1,<base64 của HMAC-SHA256 trên id.timestamp.body>, dùng phần base64 của khóa bí mật whsec_ làm khóa). Hãy phản hồi bằng bất kỳ mã 2xx nào trong vòng 10 giây; các lần thất bại được thử lại với độ trễ tăng dần theo cấp số nhân (exponential backoff) trong 3 ngày.

#### Nội dung yêu cầu: application/json, bắt buộc

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `id` | string | Có | Cũng được gửi dưới dạng header webhook-id; dùng để loại bỏ các yêu cầu thử lại trùng lặp. |
| `object` | `"event"` | Có |  |
| `type` | một trong `"analysis.completed"`, `"analysis.failed"`, `"balance.low"` | Có |  |
| `created` | integer | Có | Dấu thời gian Unix. |
| `data` | `Analysis` hoặc `BalanceLow` | Có | Các sự kiện analysis.* chứa cùng đối tượng với GET /analyses/{id}, trong đó result luôn là null; hãy lấy kết quả bằng endpoint đó. Các sự kiện balance.low chứa số dư và ngưỡng, tính bằng cent. |

**OpenAPI**

```bash
curl https://api.fileverity.com/v1/openapi.json
```