Fileverity API 文档

分析

创建图片和文档分析，通过 Prefer: wait 或轮询等待结果，取消分析，下载 PDF 报告，并了解报告对象和核验页。

查看 Markdown更新于 2026-11-04

每个分析对应一次图片或文档检测。它使用 fvimg-2（图片）或 fvdoc-3（文档）检测一个已上传的文件。请先上传文件（见文件），再创建分析。

包含请求和响应的产品概述，请参阅 AI 生成图片检测 API 和文档伪造检测 API。

创建分析

POST /analyses 返回分析对象。创建分析时会预留费用；若分析失败或被取消，预留的费用会被释放。

字段	类型	必填	说明
`model`	string	是	`fvimg-2` 或 `fvdoc-3`，或快照 ID，例如 `fvimg-2-2026-10-30`。
`file`	string	是	已上传文件的 ID。
`metadata`	object	否	最多 16 个字符串键值对。键最长 40 个字符，值最长 500 个字符。会随分析对象和 Webhook 一并返回。
`options.password`	string	否	加密文档的密码，最长 256 个字符。
`options.locale`	string	否	文档检测发现所用的语言：`en`、`fr`、`de`、`es`、`zh`、`vi` 或 `ar`。默认为 `en`。

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

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

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

等待、轮询或使用 Webhook

创建请求返回 202 和 status: processing。有三种方式获取结果：

等待：发送 Prefer: wait=N，其中 N 最大为 60 秒。请求会保持等待，直到分析完成或经过 N 秒。分析完成时返回 200；否则仍返回 202。响应头 preference-applied: wait=N 会确认该等待设置已生效。
轮询：每隔几秒调用一次 GET /analyses/{id}，直到 status 不再是 processing。
Webhook：订阅 analysis.completed 和 analysis.failed，在事件到达时获取该分析。参见 Webhooks。

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

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

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

分析处理期间，progress.stage 为 queued、reading、analyzing 或 reporting 之一；当阶段为 queued 时，position 表示排队位置。文档可能需要排队。对文档来说，等待是可选的，并且可能在结果就绪前结束，因此务必处理 202。

服务繁忙时

资源繁忙时，POST /analyses 返回 503，错误码为 service_unavailable，并带有 retry-after 响应头。不会扣费。请等待 retry-after 指定的秒数，然后使用相同的 Idempotency-Key 重试，这样重试绝不会让同一次检测运行两次。若要获得最佳吞吐量，请依次运行图片分析，而不是并行运行。

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

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

状态

状态	含义
`processing`	分析正在运行。`result` 为 `null`。
`succeeded`	结果已就绪。`report_id`、`report_url`、`summary` 和 `result` 均已设置。
`failed`	分析未能完成。`error` 中包含 `code` 和 `message`。未扣费。
`canceled`	您已取消该分析。`error.code` 为 `canceled`。未扣费。

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

报告对象

成功的分析会带有一份报告，其内容与网站、PDF 和核验页上显示的报告相同。

字段	说明
`report_id`	报告编号，`FV-XXXX-XXXX-XXXX`。
`report_url`	该报告的公开核验页。任何拿到链接的人无需账号，即可对照记录核验报告编号、文件指纹和时间戳。
`summary`	简短的判定结果。见下文。
`result.report`	完整报告。图片的 `result.report.schema` 为 `fileverity.report/1`，文档的为 `fileverity.docpro/1`。
`result.stamped_at`	为该报告签发的 RFC 3161 时间戳所对应的 Unix 时间戳，或 `null`。
`usage`	已扣费金额 `amount`（单位为美分，免费额度内的检测和失败的检测为 0）、`currency` 以及 `funding`（`trial` 或 `balance`）。
`metadata`	您传入的元数据，或 `null`。
`expires_at`	`result` 将在此 Unix 时间戳之后被移除。结果保留 7 天。

{  "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}

上面的 report 对象已缩短；实际返回的对象包含完整的检测发现。

summary 是稳定的、机器可读的判定结果。result.report 是网站和 PDF 所呈现的完整报告，其结构遵循 result.report.schema 中指明的 schema。在同一 schema 版本内，已列出的字段保持名称和含义不变，也可能新增字段，因此请忽略无法识别的字段。

图片摘要

字段	取值
`level`	`L0` 无法判定，`L1` 来源已验证，`L2` 未发现异常，`L3` 需人工复核，`L4` 高度可疑，`L5` 有力证据否定真实性。
`action`	`accept`, `review`, `reject`, `resubmit`
`assessment`	`authentic_untouched`, `authentic_locally_edited`, `ai_generated`, `undetermined`
`ai`	`labelled`, `very_likely`, `suspected`, `undecided`, `low`, `very_low`, `not_evaluated`
`edit`	`detected`, `suspected`, `suspected_record`, `review`, `generative`, `minor`, `none`, `not_applicable`, `not_evaluated`

文档摘要

字段	说明
`kind`	始终为 `docpro`。
`level`	`L0` 无法判定，`L1` 来源已验证，`L2` 未发现篡改迹象，`L3` 需人工复核，`L4` 高风险，`L5` 问题已证实。
`action`	`accept`、`note`（对照您的政策，核查报告中标出的 AI 内容）、`review`、`reject` 或 `resubmit`。
`reason`	该风险等级背后的发现或条件，例如 `clean`、`incomplete` 或某个发现 ID，或 `null`。
`findings`	重要发现的 ID。
`pages`, `images`	文档中的页数，以及已检查的内嵌照片数。
`text`	对文档文本的判定（`ai_generated`、`mixed`、`human`、`inconclusive`）；未评估文本时为 `null`。
`strong`	当所列发现中包含强证据时为 `true`，否则不出现。

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

图片报告字段

图片分析的 result.report。嵌套对象列于 API 参考。

字段	类型	必填	说明
`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	否	报告内容的指纹，供核验页使用。

文档报告字段

文档分析的 result.report。

字段	类型	必填	说明
`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	否	报告内容的指纹，供核验页使用。

获取、列出与取消

GET /analyses/{id} 返回该分析；结果在保留期内一并返回。
GET /analyses 按从新到旧的顺序列出工作区的分析。limit 取值 1 到 100（默认 20），type 可按 image 或 document 过滤，starting_after 接收上一页返回的 next_cursor。列表项不会包含 result。
POST /analyses/{id}/cancel 取消仍在处理中的文档分析，并释放已预留的费用。图片分析无法取消；过晚或已完成后的取消请求会返回 not_cancelable。

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

PDF 报告

GET /analyses/{id}/report.pdf 可在结果保留期内下载成功分析的数字签名 PDF 报告。添加 ?locale= 并取值为 en、fr、de、es、zh、vi 或 ar（默认为 en）。请发送 Authorization 请求头；响应类型为 application/pdf。

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

对于文档，页面图片和文本摘录在检测后保留 3 小时。此后 PDF 将不再包含这些内容，响应头 x-evidence-included 为 false。如需 PDF 包含这些证据，请在分析完成后立即下载。

错误

错误码	状态	原因
`file_not_found`	400	文件 ID 未知、已过期或已被使用，或者向 `upload.url` 的上传尚未完成。
`model_not_found`	404	未知模型。
`invalid_parameter`	400	字段缺失、类型错误或未知。文本模型应使用 `POST /text/detections`。
`unsupported_file`, `invalid_file`	415, 422	该模型不支持此文件格式，或文件已损坏。
`file_too_large`, `too_many_pixels`, `too_many_pages`, `document_too_long`	413	超出大小限制。
`password_required`, `wrong_password`	422	文档已加密。请发送 `options.password`。
`not_examinable`	422	文档中没有可检测的内容。未扣费。
`insufficient_balance`, `spend_limit_reached`	402	余额或该密钥的每月支出上限不足以支付此次费用。
`service_unavailable`, `analysis_failed`	503, 502	临时故障或资源繁忙。未扣费；请重试。`service_unavailable` 会带有 `retry-after` 响应头。参见服务繁忙时。
`unsupported_media_type`	415	请求体不是以 `application/json` 发送的。
`idempotency_mismatch`, `idempotency_in_progress`	409	该 `Idempotency-Key` 曾用于不同的请求体，或其首次请求仍在运行。参见幂等性。
`not_cancelable`	409	只有仍在处理中的文档才能取消。

有些失败发生在分析创建之后，例如模型无法完成检测。此时创建请求本身不会失败，而是在分析上设置 status: failed 和 error，并触发 analysis.failed Webhook。参见错误。