# API 参考

> Fileverity API 的所有接口，包含参数、请求和响应的 schema、错误码与示例，由 OpenAPI 3.1 规范生成。

来源： https://fileverity.com/zh/docs/api-reference

本参考由 API 的 OpenAPI 3.1 文档生成，该文档位于 [https://api.fileverity.com/v1/openapi.json](https://api.fileverity.com/v1/openapi.json)，因此始终与 API 保持一致。如需了解概念和指南，请从[概览](https://fileverity.com/zh/docs.md)开始。

## 约定

基础 URL：`https://api.fileverity.com/v1`。每个请求都需使用 `Authorization: Bearer <key>` 进行身份验证。所有错误使用同一种格式，详见[错误](https://fileverity.com/zh/docs/errors.md)。每个响应都带有 `x-request-id` 响应头，已通过身份验证的响应还带有[速率限制与 HTTP 头](https://fileverity.com/zh/docs/rate-limits.md)中描述的速率限制响应头。嵌套对象显示在表格下方的可折叠区域中。

## 文本检测

### 检测 AI 撰写的文本

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

将纯文本判定为 AI 撰写、部分由 AI 撰写或人类撰写，并返回其中由 AI 撰写的段落。文本在评估后即丢弃，不会被存储。计费按 Unicode 码点计数，以 1,000 字符为单位，每次请求向上取整。在评估之前被拒绝的请求不收费。测试密钥返回固定的人类撰写结果，且不收费。

#### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | 请求头 | string | 否 | 最长 255 个字符的唯一键。24 小时内使用相同的键和请求体重复该请求，将返回第一次的响应，并带有响应头 idempotent-replayed: true；相同的键搭配不同的请求体则返回 409。 |

#### 请求体：application/json，必填

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 否 | 模型 ID 或快照 ID。默认值 `"fvdoc-3-text"`。 |
| `text` | string | 是 | 纯文本，至少 100 个词，最多 100,000 个字符。 |
| `language` | 以下值之一：`"en"`、`"fr"`、`"de"`、`"es"`、`"zh"`、`null` | 否 | ISO 639-1 代码。省略时自动检测。默认值 `null`。 |

#### 响应

| 状态 | 说明 | 响应体 |
| --- | --- | --- |
| 200 | 检测结果。 | `TextDetection` |
| 400 | 请求无效。错误码：invalid_json、missing_parameter、text_too_short、unsupported_language、invalid_parameter。 | `Error` |
| 401 | 缺少 API 密钥或密钥无效。错误码：missing_api_key、invalid_api_key。 | `Error` |
| 402 | 余额或该密钥的每月支出上限不足以支付此请求。错误码：insufficient_balance、spend_limit_reached。 | `Error` |
| 404 | 未找到资源。错误码：model_not_found。 | `Error` |
| 409 | 与当前状态冲突。错误码：idempotency_mismatch、idempotency_in_progress。 | `Error` |
| 413 | 超出大小限制。错误码：text_too_long。 | `Error` |
| 415 | 不支持的媒体类型或文件格式。错误码：unsupported_media_type。 | `Error` |
| 429 | 请求过多。错误码：rate_limited。 | `Error` |
| 500 | 内部错误；未扣费。错误码：internal_error。 | `Error` |
| 502 | 分析未能完成；未扣费。错误码：analysis_failed。 | `Error` |
| 503 | 暂时不可用或繁忙；未扣费。请在 retry-after 响应头指定的秒数后重试。错误码：service_unavailable。 | `Error` |

#### 响应 200：TextDetection

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 是 |  |
| `object` | `"text.detection"` | 是 |  |
| `created` | integer | 是 | Unix 时间戳。 |
| `model` | string | 是 | 生成该结果的快照。 |
| `livemode` | boolean | 是 | 测试密钥为 false。 |
| `language` | 以下值之一：`"en"`、`"fr"`、`"de"`、`"es"`、`"zh"` | 是 |  |
| `verdict` | 以下值之一：`"ai"`、`"mixed"`、`"human"` | 是 | ai：全文读起来像 AI 撰写；mixed：人类撰写的文本中夹有 AI 撰写的段落；human：未发现 AI 撰写的段落。 |
| `score` | number | 是 | 模型对最像 AI 撰写的段落给出的分数。最小值 0。最大值 1。 |
| `ai_fraction` | number | 是 | 被评估文本中落在 AI 撰写段落内的占比。最小值 0。最大值 1。 |
| `segments` | object 数组 | 是 | AI 撰写的段落，以所提交文本中的偏移量表示，单位为 Unicode 码点。边界为大致位置，可能包含相邻的句子。 |
| `usage` | object | 是 |  |

**segments 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `start` | integer | 是 |  |
| `end` | integer | 是 | 不包含该位置。 |
| `score` | number | 是 | 最小值 0。最大值 1。 |

**usage 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `characters` | integer | 是 | 已评估的 Unicode 码点数。 |
| `free_characters` | integer | 是 | 由免费额度覆盖、不计费的字符数。 |
| `billed_units` | integer | 是 | 扣除免费字符后实际计费的 1,000 字符单位数；billed_units × 单价即为费用。 |

#### 错误码

| 错误码 | 状态 |
| --- | --- |
| `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 |

#### 示例

**请求: 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)"
```

**响应**

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

## 文件

### 上传文件

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

上传文件以供分析。4 MB 以内的文件，请在 file 字段中以 multipart/form-data 发送；响应的状态为 uploaded。大于 4 MB 的文件必须通过预签名 URL 上传：发送包含 filename、content_type 和 bytes 的 JSON（文档最大 50 MB）；响应的状态为 pending，并带有包含预签名 URL 的 upload 对象。请在其过期前，使用 PUT 和给定的请求头把文件内容发送到该 URL。文件会在分析开始时删除，最迟 24 小时后删除。每种模式下，一个工作区同时最多可保存 50 个未过期的文件和 200 MB 数据。

#### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | 请求头 | string | 否 | 最长 255 个字符的唯一键。24 小时内使用相同的键和请求体重复该请求，将返回第一次的响应，并带有响应头 idempotent-replayed: true；相同的键搭配不同的请求体则返回 409。 |

#### 请求体：multipart/form-data，必填

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `file` | string | 是 | 格式：binary。 |

#### 请求体：application/json，必填

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `filename` | string | 否 |  |
| `content_type` | string | 是 | 文件的 MIME 类型，例如 image/jpeg 或 application/pdf。 |
| `bytes` | integer | 是 | 精确大小，单位为字节。最小值 1。最大值 52,428,800。 |

#### 响应

| 状态 | 说明 | 响应体 |
| --- | --- | --- |
| 201 | 文件。 | `File` |
| 400 | 请求无效。错误码：invalid_json、missing_parameter、invalid_parameter。 | `Error` |
| 401 | 缺少 API 密钥或密钥无效。错误码：missing_api_key、invalid_api_key。 | `Error` |
| 409 | 与当前状态冲突。错误码：idempotency_mismatch、idempotency_in_progress。 | `Error` |
| 413 | 超出大小限制。错误码：file_too_large。 | `Error` |
| 415 | 不支持的媒体类型或文件格式。错误码：unsupported_media_type、unsupported_file。 | `Error` |
| 422 | 无法处理该文件。错误码：invalid_file。 | `Error` |
| 429 | 请求过多。错误码：pending_files_limit、rate_limited。 | `Error` |
| 500 | 内部错误；未扣费。错误码：internal_error。 | `Error` |

#### 响应 201：File

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 是 |  |
| `object` | `"file"` | 是 |  |
| `filename` | string 或 null | 是 |  |
| `bytes` | integer 或 null | 是 |  |
| `content_type` | string | 是 |  |
| `status` | 以下值之一：`"pending"`、`"uploaded"` | 是 | 在发送到预签名 URL 的文件内容到达之前为 pending。 |
| `livemode` | boolean | 是 | 文件仅对相同模式的密钥可见。 |
| `created` | integer | 是 | Unix 时间戳。 |
| `expires_at` | integer | 是 | 文件将在此 Unix 时间戳之后被删除。 |
| `upload` | object | 否 | 出现在 JSON 上传请求的响应中。 |

**upload 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `url` | string | 是 | 测试密钥会得到一个占位 URL（test: true）；不会上传或存储任何内容。 |
| `method` | `"PUT"` | 是 |  |
| `headers` | 值为 string 的 object | 是 |  |
| `expires_at` | integer | 是 | Unix 时间戳。 |
| `test` | `true` | 否 |  |

#### 错误码

| 错误码 | 状态 |
| --- | --- |
| `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 |

#### 示例

**请求: cURL**

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

**响应**

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

### 获取文件

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

返回该文件，以及其内容是否已到达。

#### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `id` | 路径 | string | 是 | 文件 ID。 |

#### 响应

| 状态 | 说明 | 响应体 |
| --- | --- | --- |
| 200 | 文件。 | `File` |
| 401 | 缺少 API 密钥或密钥无效。错误码：missing_api_key、invalid_api_key。 | `Error` |
| 404 | 未找到资源。错误码：not_found。 | `Error` |
| 429 | 请求过多。错误码：rate_limited。 | `Error` |
| 500 | 内部错误；未扣费。错误码：internal_error。 | `Error` |

#### 响应 200：File

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 是 |  |
| `object` | `"file"` | 是 |  |
| `filename` | string 或 null | 是 |  |
| `bytes` | integer 或 null | 是 |  |
| `content_type` | string | 是 |  |
| `status` | 以下值之一：`"pending"`、`"uploaded"` | 是 | 在发送到预签名 URL 的文件内容到达之前为 pending。 |
| `livemode` | boolean | 是 | 文件仅对相同模式的密钥可见。 |
| `created` | integer | 是 | Unix 时间戳。 |
| `expires_at` | integer | 是 | 文件将在此 Unix 时间戳之后被删除。 |
| `upload` | object | 否 | 出现在 JSON 上传请求的响应中。 |

**upload 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `url` | string | 是 | 测试密钥会得到一个占位 URL（test: true）；不会上传或存储任何内容。 |
| `method` | `"PUT"` | 是 |  |
| `headers` | 值为 string 的 object | 是 |  |
| `expires_at` | integer | 是 | Unix 时间戳。 |
| `test` | `true` | 否 |  |

#### 错误码

| 错误码 | 状态 |
| --- | --- |
| `not_found` | 404 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### 示例

**请求: cURL**

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

**响应**

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

### 删除文件

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

删除已上传的文件及其已存储的内容。

#### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `id` | 路径 | string | 是 | 文件 ID。 |

#### 响应

| 状态 | 说明 | 响应体 |
| --- | --- | --- |
| 200 | 文件已删除。 | `FileDeleted` |
| 401 | 缺少 API 密钥或密钥无效。错误码：missing_api_key、invalid_api_key。 | `Error` |
| 404 | 未找到资源。错误码：not_found。 | `Error` |
| 429 | 请求过多。错误码：rate_limited。 | `Error` |
| 500 | 内部错误；未扣费。错误码：internal_error。 | `Error` |

#### 响应 200：FileDeleted

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 是 |  |
| `object` | `"file"` | 是 |  |
| `deleted` | `true` | 是 |  |

#### 错误码

| 错误码 | 状态 |
| --- | --- |
| `not_found` | 404 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### 示例

**请求: cURL**

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

**响应**

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

## 分析

### 创建分析

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

使用 fvimg-2（图片）或 fvdoc-3（文档）分析已上传的文件。每个分析对应一次图片或文档检测。响应为 202，状态为 processing；结果通过 Webhook 送达，也可轮询 GET /analyses/{id} 获取。发送 Prefer: wait=N（最长 60 秒）可让请求保持等待，直到结果就绪；已完成的分析返回 200。价格在创建分析时预留，分析失败或被取消时释放。结果保留 7 天。资源繁忙时，API 返回 503 service_unavailable 及 retry-after 响应头，且不收费：请使用相同的 Idempotency-Key 重试，并依次运行图片分析，以获得最佳吞吐量。测试密钥返回示例结果，且永不扣费；示例报告只包含少数字段。

#### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | 请求头 | string | 否 | 最长 255 个字符的唯一键。24 小时内使用相同的键和请求体重复该请求，将返回第一次的响应，并带有响应头 idempotent-replayed: true；相同的键搭配不同的请求体则返回 409。 |
| `Prefer` | 请求头 | string | 否 | wait=N 会让请求最多保持等待 N 秒（最大 60），直到分析完成。 |

#### 请求体：application/json，必填

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | 以下值之一：`"fvimg-2"`、`"fvimg-2-2026-10-30"`、`"fvdoc-3"`、`"fvdoc-3-2026-11-03"` | 是 | 模型 ID 或快照 ID。fvimg-2 分析图片，fvdoc-3 分析文档。 |
| `file` | string | 是 | 已上传文件的 ID。 |
| `metadata` | 值为 string 的 object | 否 | 最多 16 个字符串键值对（键最长 40 个字符，值最长 500 个字符），随分析对象和 Webhook 一并返回。 |
| `options` | object | 否 |  |

**options 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `password` | string | 否 | 加密文档的密码。最大长度 256。 |
| `locale` | 以下值之一：`"en"`、`"fr"`、`"de"`、`"es"`、`"zh"`、`"vi"`、`"ar"` | 否 | 文档检测发现所用的语言。默认值 `"en"`。 |

#### 响应

| 状态 | 说明 | 响应体 |
| --- | --- | --- |
| 200 | 已完成的分析。 | `Analysis` |
| 202 | 分析正在处理中。 | `Analysis` |
| 400 | 请求无效。错误码：invalid_json、missing_parameter、file_not_found、invalid_parameter。 | `Error` |
| 401 | 缺少 API 密钥或密钥无效。错误码：missing_api_key、invalid_api_key。 | `Error` |
| 402 | 余额或该密钥的每月支出上限不足以支付此请求。错误码：insufficient_balance、spend_limit_reached。 | `Error` |
| 404 | 未找到资源。错误码：model_not_found。 | `Error` |
| 409 | 与当前状态冲突。错误码：idempotency_mismatch、idempotency_in_progress。 | `Error` |
| 413 | 超出大小限制。错误码：file_too_large、too_many_pixels、too_many_pages、document_too_long。 | `Error` |
| 415 | 不支持的媒体类型或文件格式。错误码：unsupported_media_type、unsupported_file。 | `Error` |
| 422 | 无法处理该文件。错误码：invalid_file、password_required、wrong_password、not_examinable。 | `Error` |
| 429 | 请求过多。错误码：rate_limited。 | `Error` |
| 500 | 内部错误；未扣费。错误码：internal_error。 | `Error` |
| 502 | 分析未能完成；未扣费。错误码：analysis_failed。 | `Error` |
| 503 | 暂时不可用或繁忙；未扣费。请在 retry-after 响应头指定的秒数后重试。错误码：service_unavailable。 | `Error` |

#### 响应 200：Analysis

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 是 |  |
| `object` | `"analysis"` | 是 |  |
| `created` | integer | 是 | Unix 时间戳。 |
| `model` | string | 是 | 生成该结果的快照。 |
| `livemode` | boolean | 是 |  |
| `status` | 以下值之一：`"processing"`、`"succeeded"`、`"failed"`、`"canceled"` | 是 |  |
| `file` | object | 是 |  |
| `report_id` | string 或 null | 是 | 可核验的报告编号，格式为 FV-XXXX-XXXX-XXXX。 |
| `report_url` | string 或 null | 是 | 报告的公开核验页。 |
| `summary` | `ImageSummary` 或 `DocumentSummary` 或 null | 是 | 简短而稳定的判定：图片为 ImageSummary，文档为 DocumentSummary，分析成功之前为 null。 |
| `result` | object 或 null | 是 | 状态变为 succeeded 后出现，直到结果过期为止。 |
| `error` | object 或 null | 是 |  |
| `progress` | object 或 null | 是 |  |
| `usage` | object | 是 |  |
| `metadata` | object 或 null | 是 |  |
| `completed_at` | integer 或 null | 是 |  |
| `expires_at` | integer 或 null | 是 | Unix 时间戳，此时间之后结果将被删除。 |

**file 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | string 或 null | 否 |  |
| `bytes` | integer 或 null | 否 |  |
| `format` | string 或 null | 否 |  |

**summary（ImageSummary）的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `level` | 以下值之一：`"L0"`、`"L1"`、`"L2"`、`"L3"`、`"L4"`、`"L5"` | 是 | 风险等级，L0 至 L5。 |
| `assessment` | 以下值之一：`"authentic_untouched"`、`"authentic_locally_edited"`、`"ai_generated"`、`"undetermined"` | 是 |  |
| `action` | 以下值之一：`"accept"`、`"review"`、`"reject"`、`"resubmit"` | 是 |  |
| `ai` | 以下值之一：`"labelled"`、`"very_likely"`、`"suspected"`、`"undecided"`、`"low"`、`"very_low"`、`"not_evaluated"` | 是 | 关于 AI 生成的发现。 |
| `edit` | 以下值之一：`"detected"`、`"suspected"`、`"suspected_record"`、`"review"`、`"generative"`、`"minor"`、`"none"`、`"not_applicable"`、`"not_evaluated"` | 是 | 关于局部编辑的发现。 |

**summary（DocumentSummary）的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `kind` | `"docpro"` | 是 |  |
| `level` | 以下值之一：`"L0"`、`"L1"`、`"L2"`、`"L3"`、`"L4"`、`"L5"` | 是 | 风险等级，L0 至 L5。 |
| `action` | 以下值之一：`"accept"`、`"note"`、`"review"`、`"reject"`、`"resubmit"` | 是 | note：请对照您的政策，核查报告中标出的 AI 内容。 |
| `reason` | string 或 null | 是 | 风险等级背后的发现或条件，例如 clean 或 incomplete，或某个发现 ID。 |
| `findings` | string 数组 | 是 | 重要发现的 ID。 |
| `pages` | integer | 是 | 文档的页数。 |
| `images` | integer | 是 | 已检查的内嵌照片数。 |
| `text` | 以下值之一：`"ai_generated"`、`"mixed"`、`"human"`、`"inconclusive"`、`null` | 是 | 对文档文本的判定；未评估文本时为 null。 |
| `strong` | `true` | 否 | 所列发现中包含强证据时出现。 |

**result 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `report` | `ImageReport` 或 `DocumentReport` | 否 | 完整报告。report.schema 对图片为 fileverity.report/1，对文档为 fileverity.docpro/1。 |
| `stamped_at` | integer 或 null | 否 | 为报告签发的 RFC 3161 时间戳所对应的 Unix 时间戳，或 null。 |

**report（ImageReport）的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `schema` | `"fileverity.report/1"` | 是 |  |
| `id` | string | 是 | 报告编号，FV-XXXX-XXXX-XXXX。 |
| `sample` | `true` | 否 | 出现在测试密钥返回的固定示例报告中。 |
| `issuedAt` | string | 否 | 报告签发时间，UTC 的 ISO 8601 格式。格式为 date-time。 |
| `issuer` | object | 否 | 报告的签发方。 |
| `file` | object | 否 | 被检测的图片。 |
| `pro` | object | 否 | 判定结果。取值与 summary 相同，并附带 reason。 |
| `score` | integer 或 null | 否 | 真实性评分，取值 0 到 100，步长为 5：表示证据在多大程度上支持该图片为未经编辑的真实拍摄。未评估时为 null。 |
| `confidence` | 以下值之一：`"high"`、`"medium"`、`"low"` | 否 | 该文件可供分析确定结论的程度。置信度低通常源于文件本身，例如分辨率低或压缩严重。 |
| `questions` | object | 否 | 报告回答的三个问题。 |
| `generator` | object 或 null | 否 | 为该图片指出的 AI 生成器，或 null。 |
| `regions` | object 数组 | 否 | 被标记的区域，以所显示图片的像素为单位。 |
| `provenance` | object | 否 | 文件自身记录所反映的来源信息。 |
| `digest` | string | 否 | 报告内容的指纹，供核验页使用。 |

**issuer 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | string | 否 |  |
| `operator` | string | 否 |  |
| `verify` | string | 否 | 报告的公开核验页。 |

**file 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | string 或 null | 否 |  |
| `sha256` | string | 否 | 被检测文件的 SHA-256，十六进制表示。 |
| `bytes` | integer | 否 |  |
| `width` | integer | 否 | 显示时的宽度，单位为像素。 |
| `height` | integer | 否 | 显示时的高度，单位为像素。 |
| `format` | string | 否 |  |

**pro 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `level` | 以下值之一：`"L0"`、`"L1"`、`"L2"`、`"L3"`、`"L4"`、`"L5"` | 否 | 风险等级，L0 至 L5。 |
| `action` | 以下值之一：`"accept"`、`"review"`、`"reject"`、`"resubmit"` | 否 |  |
| `assessment` | 以下值之一：`"authentic_untouched"`、`"authentic_locally_edited"`、`"ai_generated"`、`"undetermined"` | 否 |  |
| `reason` | string 或 null | 否 |  |

**questions 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `ai` | object | 否 |  |
| `edit` | object | 否 |  |
| `source` | object | 否 |  |

**ai 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `key` | 以下值之一：`"labelled"`、`"very_likely"`、`"suspected"`、`"undecided"`、`"low"`、`"very_low"`、`"not_evaluated"` | 否 |  |
| `basis` | 以下值之一：`"verified"`、`"detected"`、`"declared"`、`null` | 否 | 答案所依据的内容。 |
| `strength` | 以下值之一：`"strong"`、`"moderate"`、`"limited"`、`null` | 否 | 证据对答案的支持程度。 |
| `likelihood` | integer 或 null | 否 | AI 生成的可能性，取值 0 到 100，步长为 5，或 null。 |

**edit 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `key` | 以下值之一：`"detected"`、`"suspected"`、`"suspected_record"`、`"review"`、`"generative"`、`"minor"`、`"none"`、`"not_applicable"`、`"not_evaluated"` | 否 |  |
| `basis` | 以下值之一：`"verified"`、`"detected"`、`"declared"`、`null` | 否 | 答案所依据的内容。 |
| `strength` | 以下值之一：`"strong"`、`"moderate"`、`"limited"`、`null` | 否 | 证据对答案的支持程度。 |
| `regions` | integer | 否 | 被标记区域的数量。 |

**source 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `key` | string | 否 |  |
| `basis` | 以下值之一：`"verified"`、`"detected"`、`"declared"`、`null` | 否 | 答案所依据的内容。 |
| `strength` | 以下值之一：`"strong"`、`"moderate"`、`"limited"`、`null` | 否 | 证据对答案的支持程度。 |
| `signer` | string 或 null | 否 |  |
| `aiClaim` | boolean | 否 | 文件自身的记录是否声明为 AI 生成。 |

**generator 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | string | 否 |  |
| `basis` | string | 否 | 生成器是如何被识别的。 |

**regions 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 否 |  |
| `x` | integer | 否 |  |
| `y` | integer | 否 |  |
| `w` | integer | 否 |  |
| `h` | integer | 否 |  |
| `strength` | 以下值之一：`"high"`、`"medium"` | 否 |  |

**provenance 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `credentials` | 以下值之一：`"valid"`、`"unverified"`、`"issues"`、`"invalid"`、`"removed"`、`"none"` | 否 | 内容凭证（Content Credentials）的状态。 |
| `signer` | string 或 null | 否 |  |
| `software` | string 数组 | 否 | 文件记录中提到的软件。 |
| `camera` | string 或 null | 否 |  |
| `captured` | string 或 null | 否 | 文件中记录的拍摄时间（如有）。 |

**report（DocumentReport）的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `schema` | `"fileverity.docpro/1"` | 是 |  |
| `id` | string | 是 | 报告编号，FV-XXXX-XXXX-XXXX。 |
| `sample` | `true` | 否 | 出现在测试密钥返回的固定示例报告中。 |
| `issuedAt` | string | 否 | 报告签发时间，UTC 的 ISO 8601 格式。格式为 date-time。 |
| `receivedAt` | string | 否 | 文件接收时间，UTC 的 ISO 8601 格式。格式为 date-time。 |
| `issuer` | object | 否 | 报告的签发方。 |
| `file` | object | 否 | 被检测的文档。 |
| `level` | 以下值之一：`"L0"`、`"L1"`、`"L2"`、`"L3"`、`"L4"`、`"L5"` | 否 | 风险等级，L0 至 L5。 |
| `action` | 以下值之一：`"accept"`、`"note"`、`"review"`、`"reject"`、`"resubmit"` | 否 |  |
| `reason` | string 或 null | 否 | 该风险等级背后的发现或条件。 |
| `findings` | object 数组 | 否 | 该风险等级背后的各项发现，每项发现都附有其涉及的页面和内嵌照片。 |
| `text` | object | 否 | 文档文本的检测结果。 |
| `images` | object 数组 | 否 | 内嵌的照片和图形，按在文档中的顺序编号。 |
| `structure` | object 或 null | 否 | 文件的编辑历史，未检查时为 null。 |
| `provenance` | object | 否 | 文件自身记录所反映的来源信息。 |
| `digest` | string | 否 | 报告内容的指纹，供核验页使用。 |

**issuer 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | string | 否 |  |
| `operator` | string | 否 |  |
| `verify` | string | 否 | 报告的公开核验页。 |

**file 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | string 或 null | 否 |  |
| `sha256` | string | 否 | 被检测文件的 SHA-256，十六进制表示。 |
| `bytes` | integer | 否 |  |
| `format` | string | 否 |  |
| `pages` | integer | 否 |  |
| `textLayer` | 以下值之一：`"present"`、`"partial"`、`"absent"` | 否 | 文档是否带有文本层。 |

**findings 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 否 |  |
| `basis` | 以下值之一：`"verified"`、`"detected"`、`"declared"` | 否 |  |
| `strength` | 以下值之一：`"strong"`、`"moderate"`、`"limited"` | 否 |  |
| `material` | boolean | 否 | 该发现是否计入风险等级。 |
| `pages` | integer 数组 | 否 |  |
| `images` | integer 数组 | 否 |  |

**text 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `status` | 以下值之一：`"evaluated"`、`"insufficient_text"`、`"unsupported_language"`、`"no_text"` | 否 |  |
| `verdict` | 以下值之一：`"ai_generated"`、`"mixed"`、`"human"`、`"inconclusive"` | 否 | status 为 evaluated 时出现。 |
| `words` | integer | 否 |  |
| `languages` | string 数组 | 否 |  |
| `passages` | integer | 否 | 被标出段落的数量。 |

**images 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `n` | integer | 否 |  |
| `pages` | integer 数组 | 否 |  |
| `kind` | 以下值之一：`"photo"`、`"graphic"` | 否 |  |
| `width` | integer | 否 |  |
| `height` | integer | 否 |  |
| `level` | 以下值之一：`"L0"`、`"L1"`、`"L2"`、`"L3"`、`"L4"`、`"L5"`、`null` | 否 |  |
| `assessment` | 以下值之一：`"authentic_untouched"`、`"authentic_locally_edited"`、`"ai_generated"`、`"undetermined"`、`null` | 否 |  |
| `ai` | 以下值之一：`"labelled"`、`"very_likely"`、`"suspected"`、`"undecided"`、`"low"`、`"very_low"`、`"not_evaluated"`、`null` | 否 |  |
| `edit` | 以下值之一：`"detected"`、`"suspected"`、`"suspected_record"`、`"review"`、`"generative"`、`"minor"`、`"none"`、`"not_applicable"`、`"not_evaluated"`、`null` | 否 |  |

**structure 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `revisions` | integer 或 null | 否 |  |
| `changedPages` | integer 数组 | 否 |  |
| `addedPages` | integer | 否 |  |
| `signatures` | integer | 否 |  |

**provenance 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `credentials` | string | 否 | 内容凭证（Content Credentials）的状态。 |
| `signer` | string 或 null | 否 |  |
| `aiClaim` | boolean | 否 | 文件自身的记录是否声明为 AI 生成。 |
| `software` | string 数组 | 否 |  |
| `created` | string 或 null | 否 |  |
| `modified` | string 或 null | 否 |  |
| `revisions` | integer 或 null | 否 |  |
| `signed` | boolean 或 null | 否 |  |

**error 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | 以下值之一：`"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"` | 否 |  |
| `message` | string | 否 |  |

**progress 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `stage` | 以下值之一：`"queued"`、`"reading"`、`"analyzing"`、`"reporting"` | 否 |  |
| `done` | integer | 否 | 当前阶段已完成的单位数（已知时）；否则为 0。 |
| `total` | integer | 否 | 当前阶段的单位总数（已知时）；否则为 0。 |
| `position` | integer | 否 | 处于排队阶段时的队列位置。 |

**usage 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `amount` | integer | 否 | 费用，单位为美分；免费额度内的检测和失败的检测为 0。 |
| `currency` | `"usd"` | 否 |  |
| `funding` | 以下值之一：`"trial"`、`"balance"`、`null` | 否 |  |

#### 错误码

| 错误码 | 状态 |
| --- | --- |
| `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 |

#### 示例

**请求: 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"}'
```

**响应**

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

### 列出分析

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

列出您工作区中的图片和文档分析，最新的在前。测试密钥始终返回空列表。

#### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `limit` | 查询 | integer | 否 | 默认值 `20`。最小值 1。最大值 100。 |
| `starting_after` | 查询 | string | 否 | 游标：上一页返回的 next_cursor。 |
| `type` | 查询 | 以下值之一：`"image"`、`"document"` | 否 |  |

#### 响应

| 状态 | 说明 | 响应体 |
| --- | --- | --- |
| 200 | 分析列表的一页。 | `AnalysisList` |
| 400 | 请求无效。错误码：invalid_parameter。 | `Error` |
| 401 | 缺少 API 密钥或密钥无效。错误码：missing_api_key、invalid_api_key。 | `Error` |
| 429 | 请求过多。错误码：rate_limited。 | `Error` |
| 500 | 内部错误；未扣费。错误码：internal_error。 | `Error` |

#### 响应 200：AnalysisList

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `object` | `"list"` | 是 |  |
| `data` | `Analysis` 数组 | 是 |  |
| `has_more` | boolean | 是 |  |
| `next_cursor` | string 或 null | 是 | 作为 starting_after 传入，以获取下一页。 |

**data 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 是 |  |
| `object` | `"analysis"` | 是 |  |
| `created` | integer | 是 | Unix 时间戳。 |
| `model` | string | 是 | 生成该结果的快照。 |
| `livemode` | boolean | 是 |  |
| `status` | 以下值之一：`"processing"`、`"succeeded"`、`"failed"`、`"canceled"` | 是 |  |
| `file` | object | 是 |  |
| `report_id` | string 或 null | 是 | 可核验的报告编号，格式为 FV-XXXX-XXXX-XXXX。 |
| `report_url` | string 或 null | 是 | 报告的公开核验页。 |
| `summary` | `ImageSummary` 或 `DocumentSummary` 或 null | 是 | 简短而稳定的判定：图片为 ImageSummary，文档为 DocumentSummary，分析成功之前为 null。 |
| `result` | object 或 null | 是 | 状态变为 succeeded 后出现，直到结果过期为止。 |
| `error` | object 或 null | 是 |  |
| `progress` | object 或 null | 是 |  |
| `usage` | object | 是 |  |
| `metadata` | object 或 null | 是 |  |
| `completed_at` | integer 或 null | 是 |  |
| `expires_at` | integer 或 null | 是 | Unix 时间戳，此时间之后结果将被删除。 |

**file 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | string 或 null | 否 |  |
| `bytes` | integer 或 null | 否 |  |
| `format` | string 或 null | 否 |  |

**result 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `report` | `ImageReport` 或 `DocumentReport` | 否 | 完整报告。report.schema 对图片为 fileverity.report/1，对文档为 fileverity.docpro/1。 |
| `stamped_at` | integer 或 null | 否 | 为报告签发的 RFC 3161 时间戳所对应的 Unix 时间戳，或 null。 |

**error 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | 以下值之一：`"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"` | 否 |  |
| `message` | string | 否 |  |

**progress 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `stage` | 以下值之一：`"queued"`、`"reading"`、`"analyzing"`、`"reporting"` | 否 |  |
| `done` | integer | 否 | 当前阶段已完成的单位数（已知时）；否则为 0。 |
| `total` | integer | 否 | 当前阶段的单位总数（已知时）；否则为 0。 |
| `position` | integer | 否 | 处于排队阶段时的队列位置。 |

**usage 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `amount` | integer | 否 | 费用，单位为美分；免费额度内的检测和失败的检测为 0。 |
| `currency` | `"usd"` | 否 |  |
| `funding` | 以下值之一：`"trial"`、`"balance"`、`null` | 否 |  |

#### 错误码

| 错误码 | 状态 |
| --- | --- |
| `invalid_parameter` | 400 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### 示例

**请求: cURL**

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

**响应**

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

### 获取分析

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

返回该分析；分析成功后，在过期之前同时返回其结果。

#### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `id` | 路径 | string | 是 | 分析 ID。 |

#### 响应

| 状态 | 说明 | 响应体 |
| --- | --- | --- |
| 200 | 该分析。 | `Analysis` |
| 401 | 缺少 API 密钥或密钥无效。错误码：missing_api_key、invalid_api_key。 | `Error` |
| 404 | 未找到资源。错误码：not_found。 | `Error` |
| 429 | 请求过多。错误码：rate_limited。 | `Error` |
| 500 | 内部错误；未扣费。错误码：internal_error。 | `Error` |

#### 响应 200：Analysis

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 是 |  |
| `object` | `"analysis"` | 是 |  |
| `created` | integer | 是 | Unix 时间戳。 |
| `model` | string | 是 | 生成该结果的快照。 |
| `livemode` | boolean | 是 |  |
| `status` | 以下值之一：`"processing"`、`"succeeded"`、`"failed"`、`"canceled"` | 是 |  |
| `file` | object | 是 |  |
| `report_id` | string 或 null | 是 | 可核验的报告编号，格式为 FV-XXXX-XXXX-XXXX。 |
| `report_url` | string 或 null | 是 | 报告的公开核验页。 |
| `summary` | `ImageSummary` 或 `DocumentSummary` 或 null | 是 | 简短而稳定的判定：图片为 ImageSummary，文档为 DocumentSummary，分析成功之前为 null。 |
| `result` | object 或 null | 是 | 状态变为 succeeded 后出现，直到结果过期为止。 |
| `error` | object 或 null | 是 |  |
| `progress` | object 或 null | 是 |  |
| `usage` | object | 是 |  |
| `metadata` | object 或 null | 是 |  |
| `completed_at` | integer 或 null | 是 |  |
| `expires_at` | integer 或 null | 是 | Unix 时间戳，此时间之后结果将被删除。 |

**file 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | string 或 null | 否 |  |
| `bytes` | integer 或 null | 否 |  |
| `format` | string 或 null | 否 |  |

**result 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `report` | `ImageReport` 或 `DocumentReport` | 否 | 完整报告。report.schema 对图片为 fileverity.report/1，对文档为 fileverity.docpro/1。 |
| `stamped_at` | integer 或 null | 否 | 为报告签发的 RFC 3161 时间戳所对应的 Unix 时间戳，或 null。 |

**error 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | 以下值之一：`"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"` | 否 |  |
| `message` | string | 否 |  |

**progress 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `stage` | 以下值之一：`"queued"`、`"reading"`、`"analyzing"`、`"reporting"` | 否 |  |
| `done` | integer | 否 | 当前阶段已完成的单位数（已知时）；否则为 0。 |
| `total` | integer | 否 | 当前阶段的单位总数（已知时）；否则为 0。 |
| `position` | integer | 否 | 处于排队阶段时的队列位置。 |

**usage 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `amount` | integer | 否 | 费用，单位为美分；免费额度内的检测和失败的检测为 0。 |
| `currency` | `"usd"` | 否 |  |
| `funding` | 以下值之一：`"trial"`、`"balance"`、`null` | 否 |  |

#### 错误码

| 错误码 | 状态 |
| --- | --- |
| `not_found` | 404 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### 示例

**请求: cURL**

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

**响应**

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

### 取消分析

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

取消仍在处理中的文档分析，并释放其费用。图片分析一经创建便无法取消。

#### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `id` | 路径 | string | 是 | 分析 ID。 |
| `Idempotency-Key` | 请求头 | string | 否 | 最长 255 个字符的唯一键。24 小时内使用相同的键和请求体重复该请求，将返回第一次的响应，并带有响应头 idempotent-replayed: true；相同的键搭配不同的请求体则返回 409。 |

#### 响应

| 状态 | 说明 | 响应体 |
| --- | --- | --- |
| 200 | 已取消的分析。 | `Analysis` |
| 400 | 请求无效。错误码：invalid_parameter。 | `Error` |
| 401 | 缺少 API 密钥或密钥无效。错误码：missing_api_key、invalid_api_key。 | `Error` |
| 404 | 未找到资源。错误码：not_found。 | `Error` |
| 409 | 与当前状态冲突。错误码：not_cancelable、idempotency_mismatch、idempotency_in_progress。 | `Error` |
| 429 | 请求过多。错误码：rate_limited。 | `Error` |
| 500 | 内部错误；未扣费。错误码：internal_error。 | `Error` |

#### 响应 200：Analysis

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 是 |  |
| `object` | `"analysis"` | 是 |  |
| `created` | integer | 是 | Unix 时间戳。 |
| `model` | string | 是 | 生成该结果的快照。 |
| `livemode` | boolean | 是 |  |
| `status` | 以下值之一：`"processing"`、`"succeeded"`、`"failed"`、`"canceled"` | 是 |  |
| `file` | object | 是 |  |
| `report_id` | string 或 null | 是 | 可核验的报告编号，格式为 FV-XXXX-XXXX-XXXX。 |
| `report_url` | string 或 null | 是 | 报告的公开核验页。 |
| `summary` | `ImageSummary` 或 `DocumentSummary` 或 null | 是 | 简短而稳定的判定：图片为 ImageSummary，文档为 DocumentSummary，分析成功之前为 null。 |
| `result` | object 或 null | 是 | 状态变为 succeeded 后出现，直到结果过期为止。 |
| `error` | object 或 null | 是 |  |
| `progress` | object 或 null | 是 |  |
| `usage` | object | 是 |  |
| `metadata` | object 或 null | 是 |  |
| `completed_at` | integer 或 null | 是 |  |
| `expires_at` | integer 或 null | 是 | Unix 时间戳，此时间之后结果将被删除。 |

**file 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | string 或 null | 否 |  |
| `bytes` | integer 或 null | 否 |  |
| `format` | string 或 null | 否 |  |

**result 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `report` | `ImageReport` 或 `DocumentReport` | 否 | 完整报告。report.schema 对图片为 fileverity.report/1，对文档为 fileverity.docpro/1。 |
| `stamped_at` | integer 或 null | 否 | 为报告签发的 RFC 3161 时间戳所对应的 Unix 时间戳，或 null。 |

**error 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | 以下值之一：`"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"` | 否 |  |
| `message` | string | 否 |  |

**progress 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `stage` | 以下值之一：`"queued"`、`"reading"`、`"analyzing"`、`"reporting"` | 否 |  |
| `done` | integer | 否 | 当前阶段已完成的单位数（已知时）；否则为 0。 |
| `total` | integer | 否 | 当前阶段的单位总数（已知时）；否则为 0。 |
| `position` | integer | 否 | 处于排队阶段时的队列位置。 |

**usage 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `amount` | integer | 否 | 费用，单位为美分；免费额度内的检测和失败的检测为 0。 |
| `currency` | `"usd"` | 否 |  |
| `funding` | 以下值之一：`"trial"`、`"balance"`、`null` | 否 |  |

#### 错误码

| 错误码 | 状态 |
| --- | --- |
| `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 |

#### 示例

**请求: cURL**

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

**响应**

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

### 下载 PDF 报告

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

在结果保留期间，返回成功分析的数字签名 PDF 报告。测试密钥返回 404。页面图片等文档证据在分析完成后的 3 小时内可用；此后 PDF 不再包含这些证据，并通过 x-evidence-included: false 标示。

#### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `id` | 路径 | string | 是 | 分析 ID。 |
| `locale` | 查询 | 以下值之一：`"en"`、`"fr"`、`"de"`、`"es"`、`"zh"`、`"vi"`、`"ar"` | 否 | 默认值 `"en"`。 |

#### 响应

| 状态 | 说明 | 响应体 |
| --- | --- | --- |
| 200 | PDF 报告。 | PDF 文件 |
| 400 | 请求无效。错误码：invalid_parameter。 | `Error` |
| 401 | 缺少 API 密钥或密钥无效。错误码：missing_api_key、invalid_api_key。 | `Error` |
| 404 | 未找到资源。错误码：not_found。 | `Error` |
| 429 | 请求过多。错误码：rate_limited。 | `Error` |
| 500 | 内部错误；未扣费。错误码：internal_error。 | `Error` |

#### 错误码

| 错误码 | 状态 |
| --- | --- |
| `invalid_parameter` | 400 |
| `not_found` | 404 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### 示例

**请求: 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
```

## 模型

### 列出模型

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

列出您的 API 密钥可用的模型。

#### 响应

| 状态 | 说明 | 响应体 |
| --- | --- | --- |
| 200 | 可用的模型。 | `ModelList` |
| 401 | 缺少 API 密钥或密钥无效。错误码：missing_api_key、invalid_api_key。 | `Error` |
| 429 | 请求过多。错误码：rate_limited。 | `Error` |
| 500 | 内部错误；未扣费。错误码：internal_error。 | `Error` |

#### 响应 200：ModelList

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `object` | `"list"` | 是 |  |
| `data` | `Model` 数组 | 是 |  |

**data 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 是 |  |
| `object` | `"model"` | 是 |  |
| `created` | integer | 是 | 当前快照的 Unix 时间戳。 |
| `owned_by` | string | 是 |  |
| `name` | string | 是 |  |
| `type` | 以下值之一：`"image"`、`"document"`、`"text"` | 是 |  |
| `description` | string | 是 |  |
| `snapshot` | string | 是 | 该 ID 当前指向的带日期的快照。 |
| `status` | 以下值之一：`"available"`、`"preview"`、`"deprecated"` | 是 |  |
| `input` | object | 是 | 接受的输入。文件列出格式和大小限制；文本列出语言和长度限制。 |
| `output` | object | 是 |  |
| `pricing` | object | 是 |  |

**input 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `formats` | string 数组 | 否 |  |
| `max_bytes` | integer | 否 |  |
| `max_megapixels` | integer | 否 |  |
| `max_pages` | integer | 否 |  |
| `languages` | string 数组 | 否 |  |
| `min_words` | integer | 否 |  |
| `max_characters` | integer | 否 |  |

**output 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `schema` | string | 是 | 分析结果中报告所采用的 schema。 |

**pricing 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `currency` | `"usd"` | 是 |  |
| `unit` | string | 是 |  |
| `unit_amount` | integer | 是 | 每单位价格，单位为美分。 |

#### 错误码

| 错误码 | 状态 |
| --- | --- |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### 示例

**请求: cURL**

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

**响应**

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

### 获取模型

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

按 ID 或快照 ID 获取模型。

#### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `model` | 路径 | string | 是 | 模型 ID 或快照 ID。 |

#### 响应

| 状态 | 说明 | 响应体 |
| --- | --- | --- |
| 200 | 该模型。 | `Model` |
| 401 | 缺少 API 密钥或密钥无效。错误码：missing_api_key、invalid_api_key。 | `Error` |
| 404 | 未找到资源。错误码：model_not_found。 | `Error` |
| 429 | 请求过多。错误码：rate_limited。 | `Error` |
| 500 | 内部错误；未扣费。错误码：internal_error。 | `Error` |

#### 响应 200：Model

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 是 |  |
| `object` | `"model"` | 是 |  |
| `created` | integer | 是 | 当前快照的 Unix 时间戳。 |
| `owned_by` | string | 是 |  |
| `name` | string | 是 |  |
| `type` | 以下值之一：`"image"`、`"document"`、`"text"` | 是 |  |
| `description` | string | 是 |  |
| `snapshot` | string | 是 | 该 ID 当前指向的带日期的快照。 |
| `status` | 以下值之一：`"available"`、`"preview"`、`"deprecated"` | 是 |  |
| `input` | object | 是 | 接受的输入。文件列出格式和大小限制；文本列出语言和长度限制。 |
| `output` | object | 是 |  |
| `pricing` | object | 是 |  |

**input 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `formats` | string 数组 | 否 |  |
| `max_bytes` | integer | 否 |  |
| `max_megapixels` | integer | 否 |  |
| `max_pages` | integer | 否 |  |
| `languages` | string 数组 | 否 |  |
| `min_words` | integer | 否 |  |
| `max_characters` | integer | 否 |  |

**output 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `schema` | string | 是 | 分析结果中报告所采用的 schema。 |

**pricing 的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `currency` | `"usd"` | 是 |  |
| `unit` | string | 是 |  |
| `unit_amount` | integer | 是 | 每单位价格，单位为美分。 |

#### 错误码

| 错误码 | 状态 |
| --- | --- |
| `model_not_found` | 404 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### 示例

**请求: cURL**

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

**响应**

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

## Webhook 事件

Fileverity 会向您的 Webhook 端点发送这些事件。校验和投递规则参见 [Webhooks](https://fileverity.com/zh/docs/webhooks.md)。

### 事件 analysis.completed

按照 Standard Webhooks 规范投递到您的 Webhook 端点：请求头 webhook-id、webhook-timestamp 和 webhook-signature（v1,<id.timestamp.body 的 Base64 HMAC-SHA256>，以 whsec_ 密钥中的 Base64 部分作为密钥）。请在 10 秒内返回任意 2xx 响应；失败后会以指数退避重试，持续 3 天。

#### 请求体：application/json，必填

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 是 | 同时作为 webhook-id 请求头发送；可用它对重试去重。 |
| `object` | `"event"` | 是 |  |
| `type` | 以下值之一：`"analysis.completed"`、`"analysis.failed"`、`"balance.low"` | 是 |  |
| `created` | integer | 是 | Unix 时间戳。 |
| `data` | `Analysis` 或 `BalanceLow` | 是 | analysis.* 事件携带的对象与 GET /analyses/{id} 相同，但 result 始终为 null；请通过该接口获取结果。balance.low 事件携带以美分为单位的余额和阈值。 |

**data（BalanceLow）的字段**

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `balance` | integer | 是 | 余额，单位为美分。 |
| `threshold` | integer | 是 | 提醒阈值，单位为美分。 |

### 事件 analysis.failed

按照 Standard Webhooks 规范投递到您的 Webhook 端点：请求头 webhook-id、webhook-timestamp 和 webhook-signature（v1,<id.timestamp.body 的 Base64 HMAC-SHA256>，以 whsec_ 密钥中的 Base64 部分作为密钥）。请在 10 秒内返回任意 2xx 响应；失败后会以指数退避重试，持续 3 天。

#### 请求体：application/json，必填

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 是 | 同时作为 webhook-id 请求头发送；可用它对重试去重。 |
| `object` | `"event"` | 是 |  |
| `type` | 以下值之一：`"analysis.completed"`、`"analysis.failed"`、`"balance.low"` | 是 |  |
| `created` | integer | 是 | Unix 时间戳。 |
| `data` | `Analysis` 或 `BalanceLow` | 是 | analysis.* 事件携带的对象与 GET /analyses/{id} 相同，但 result 始终为 null；请通过该接口获取结果。balance.low 事件携带以美分为单位的余额和阈值。 |

### 事件 balance.low

按照 Standard Webhooks 规范投递到您的 Webhook 端点：请求头 webhook-id、webhook-timestamp 和 webhook-signature（v1,<id.timestamp.body 的 Base64 HMAC-SHA256>，以 whsec_ 密钥中的 Base64 部分作为密钥）。请在 10 秒内返回任意 2xx 响应；失败后会以指数退避重试，持续 3 天。

#### 请求体：application/json，必填

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 是 | 同时作为 webhook-id 请求头发送；可用它对重试去重。 |
| `object` | `"event"` | 是 |  |
| `type` | 以下值之一：`"analysis.completed"`、`"analysis.failed"`、`"balance.low"` | 是 |  |
| `created` | integer | 是 | Unix 时间戳。 |
| `data` | `Analysis` 或 `BalanceLow` | 是 | analysis.* 事件携带的对象与 GET /analyses/{id} 相同，但 result 始终为 null；请通过该接口获取结果。balance.low 事件携带以美分为单位的余额和阈值。 |

**OpenAPI**

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