如何选择 AI 检测 API：集成前要核查的十件事

选择 AI 检测 API，要核查十件决定它能否稳定用于生产的事：它检测什么、返回什么；输入限制；结果如何送达；Webhook 是否签名；重试是否安全；错误与速率限制如何表现；它保留什么数据、保留多久；结果能否审计并对应到具体的模型版本；以及检测失败或测试请求是否计费。其中大部分在写任何代码之前，就能从服务商的文档中得到答案，其余几项需要一次简短的试点。

本文写给把检测服务接入收件、理赔、开户或内容审核流程的工程师和技术采购人员。它评估的是接口，而不是检测器本身。检测的准确率、误报和复核工作量，请参阅企业选择 AI 生成图片检测工具的采购指南和准确率与误报指南。一个在您的文件上表现良好的检测器，如果外围的 API 难以重试、难以审计或难以结算，仍然可能在生产中出问题。

每一项都会说明它为什么重要、如何在任何服务商的文档中核实，以及 Fileverity API 写明了什么，并附上 API 文档 的链接。同样的十个问题适用于每一家候选服务商，本文不点名、也不排名任何服务商。

十项评估一览

下图显示每一项能在哪里找到答案。文档说明服务商承诺了什么，测试密钥展示请求与响应的形态，只有用您自己的文件做试点，才能看到耗时、删除和计费的真实情况。

范围与输入

检测类型与输出

为什么重要。 “AI 检测”包含不同的任务：图片是否由 AI 生成或被编辑，文档是否被篡改或含有 AI 撰写的段落，纯文本是否由 AI 撰写。支持其中一种的服务商，不一定支持另一种。只返回一个数字、没有范围也没有证据的响应，既难以据此行动，也难以在事后辩护。复核人员需要知道发现针对的是什么，您的路由代码则需要一个稳定的、机器可读的字段。

如何核实。 列出您需要的任务，在文档中按名称逐一找到。打开响应结构，查看四点：与详细发现分开的机器可读摘要（结论、等级或建议措施）；人能读懂的证据；区别于“阴性”的“无法评估”状态；以及结构版本号。请服务商提供几类响应样例：命中、未命中、无法判定和失败。采购指南中的能力覆盖表说明了如何记录这些答复。

Fileverity 的文档写明了什么。 三个模型，均由 GET /models 列出其限制与快照：图片用 fvimg-2，文档用 fvdoc-3，纯文本用 fvdoc-3-text。图片和文档检测返回完整报告，含摘要等级与建议措施、详细发现、报告编号和加盖封印的 PDF；文本检测返回检测结果，含判定（AI 撰写、混合或人类撰写）、分数和标出的段落。文档明确说明，文本结果是统计估计而非作者身份的证明，不应单独用于决定会影响个人的事项。参见 概览、报告对象 和 文本检测，也可查看 AI 生成图片检测 API 与 文档伪造检测 API 页面。

输入限制

为什么重要。 限制决定您实际收到的文件能不能顺利通过：手机拍的照片、截图、扫描件、多页 PDF、有密码的文件、长文本。第一次在生产环境中遇到的限制，表现为请求失败和用户抱怨。

如何核实。 找到每种类型的限制：支持的格式、最大体积、像素数或页数、文本长度与语言。确认大文件如何上传（单次请求还是预签名上传），格式是按文件内容识别还是相信文件名，以及每一种超限会返回什么。独立的错误码是好信号；静默截断或笼统的 400 则不是。然后提交您实际会收到的最大、最小和最难处理的文件，例如理赔材料或信贷申请附件。

Fileverity 的文档写明了什么。 文件列出每个模型支持的格式与限制、直接的 multipart 上传、较大文件使用的预签名上传、按文件内容识别格式，以及每项限制对应的错误码。加密文档可通过密码选项处理（分析）。文本长度与语言见 文本检测。

结果与送达

等待结果

为什么重要。 实验室里几秒完成的调用，在负载下可能更久，而您自己的平台也有超时：无服务器函数、网关、面向用户的请求。服务商的应答方式有两种。同步调用在响应中直接返回结果；异步调用立即返回一个状态，结果稍后再取。为第一种方式写的集成遇到第二种，就会丢结果或阻塞用户。下图展示了异步结果到达您代码的三种方式。

如何核实。 查看状态生命周期（processing、succeeded、failed、canceled），以及服务商是否能保持请求打开、文档写明的最长等待时间。确认如何轮询、间隔多久，容量繁忙时会怎样，排队中的任务是否报告位置，任务能否免费取消。带有 Retry-After 头的 503（该头由 RFC 9110 定义）会告诉您的代码该怎么做。试点时，按预期规模测量最慢文件类型的端到端耗时。瞬间返回的测试模式在这一点上说明不了任何问题。

Fileverity 的文档写明了什么。 文本检测是同步的，结果就在响应中。图片和文档检测是异步的：创建后返回 202 和 status: processing。您可以用 Prefer: wait 请求头保持请求打开，轮询 GET /analyses/{id}，或订阅 Webhook；即使选择等待，也应处理 202，因为文档可能进入队列。容量繁忙时，创建请求返回带 retry-after 的 503 service_unavailable，且不计费。仍在处理中的文档检测可以取消，不计费。参见 等待、轮询或使用 Webhook和 服务繁忙时。

Webhook 签名

为什么重要。 Webhook 端点是一个公开的 URL，接收会改动您案件数据的请求。不做验证，任何发现它的人都可以发来伪造的“未命中”结果。投递本身也天然不可靠：您的服务器会重启，所以发送方必须重试，随之产生重复和乱序的事件。

如何核实。 查看文档是否写明签名方案：每个端点独立的密钥、对原始请求体的签名，以及用来拒绝过期请求的时间戳。Standard Webhooks 规范是一套开放约定，使用 webhook-id、webhook-timestamp 和 webhook-signature 请求头以及 HMAC-SHA256 签名，现成的库就能验证。还要看密钥如何轮换、重试计划及何时停止、是否有稳定的事件 ID 用于去重、载荷里是结果本身还是只有一个 ID、失败如何通知您（投递日志、重发、被停用的端点），以及能否触发测试事件。试点时，先让您的端点故意返回一次错误，再发送被篡改的请求体和过期的时间戳。

Fileverity 的文档写明了什么。 Webhook 遵循 Standard Webhooks：三个请求头，以及对事件 ID、时间戳和原始请求体计算的 HMAC-SHA256 签名。签名密钥只显示一次，可以轮换；文档提供 JavaScript 和 Python 的验证代码。投递至少一次且不保证顺序，请按 webhook-id 去重。投递失败后会以逐渐拉长的间隔重试数天；持续失败的端点会被停用，并通过电子邮件通知工作区所有者；控制台列出近期投递，可重新发送。Send test 会投递一个已签名的示例事件。事件本身不含结果，请用 GET /analyses/{id} 获取。文本检测是同步的，不发送 Webhook；测试密钥从不发送事件。参见 校验签名和 投递与重试。

重试与负载下的可靠性

幂等与重试

为什么重要。 网络可能在您发出请求与收到响应之间中断。如果重试可能创建第二次检测，您会付两次钱，还可能开出重复的案件；如果从不重试，又会丢失工作。幂等键让服务商认出这是一次重试，并返回第一次的结果。

如何核实。 查看每个会创建对象或产生费用的端点是否支持幂等键请求头。阅读各种情形：同一个键重放时会怎样（返回相同响应，并标明是重放）；同一个键搭配不同请求体时（应当被拒绝，而不是悄悄接受）；第一次请求仍在运行时；出错之后；以及键保留多久、作用范围是什么。该请求头由一份 IETF 草案描述，截至 2026 年 11 月它还不是 RFC，各家服务商的细节不尽相同，务必实测。试点时，把同一个请求发两次，并在请求中途断开连接，然后确认只有一次结果、一次计费。

Fileverity 的文档写明了什么。 Idempotency-Key 请求头适用于每一个 POST 端点：文本检测、文件上传、创建和取消检测。重放时返回已保存的响应并带 idempotent-replayed: true，不会重新运行，也不会重复计费。同一个键搭配不同请求体，返回 409 idempotency_mismatch；第一次请求仍在运行时重用同一个键，返回 409 idempotency_in_progress。错误响应不会被保存，所以出错后重试会重新执行请求。键按工作区、模式（live 或 test）和端点划分作用范围，并保留文档写明的一段时间。参见 幂等性。

错误与请求 ID

为什么重要。 您的代码需要决定重试什么、修正什么、向用户展示什么，以及把什么交给服务商的支持团队。用自然语言写的错误信息会随时间变化，解析它们的代码会随之失效。请求 ID 让双方日后都能找到同一次请求。

如何核实。 查看错误是否采用统一的 JSON 结构，带有稳定的机器可读错误码，并与面向人的信息分开；是否有列出全部错误码、HTTP 状态及是否应重试的表格；每个响应（包括成功的）是否在响应头中带有请求 ID。确认文档是否写明失败的检测是否计费。试点时，逐类触发故障（无效密钥、超大文件、不支持的格式、未知 ID、余额为零），确认仅凭错误码就能区分它们。

Fileverity 的文档写明了什么。 错误包含 type、code、message、param 和 request_id，文档建议依据 code 而不是 message 来分支处理。每个响应都带 x-request-id 请求头，错误码表由 API 自身的定义生成。文档列出哪些错误应当重试、哪些应先修正，以出错告终的检测不计费。联系 hello@fileverity.com 或通过联系页面时，请附上请求 ID。参见 错误。

速率限制

为什么重要。 突发流量，例如导入历史积压或月末批处理，可能触发限制。处理不当，就会变成失败和重试，让情况更糟。限制也说明了服务商期望的用法：把请求分散开，并优先使用 Webhook 而不是密集轮询。

如何核实。 查看每个密钥或账户的限额及其时间窗口、显示限额与剩余次数及重置时间的响应头，以及带 Retry-After 头的 429 响应（RFC 6585 定义了 429 状态码）。还要看其他上限，例如并发或待处理的上传，以及如何申请更高限额。如果服务商的测试模式适用相同的限制，先在测试模式下跑一次突发流量。

Fileverity 的文档写明了什么。 每个 API 密钥有按分钟计算的限额，覆盖所有端点，包括返回错误的请求。每个已认证响应都带 x-ratelimit-limit-requests、x-ratelimit-remaining-requests 和 x-ratelimit-reset-requests，429 rate_limited 带 retry-after。对未过期的已上传文件另有单独上限，触发时返回 pending_files_limit，不带 retry-after。测试密钥与 Live 密钥共用速率限制，所以可以用测试密钥演练退避逻辑。更高的限额可通过商务团队协商。参见 速率限制与 HTTP 头。

数据、证据与成本

数据留存

为什么重要。 提交检测的文件往往含有个人信息或商业机密：理赔照片、工资单、合同。服务商因此成为这些数据的受托处理方。您需要知道保存了什么、存在哪里、保存多久、谁能访问，以及数据是否被用来训练模型。

如何核实。 要求按数据类别逐项回答：上传的文件、提交的文本、衍生数据、结果、日志和备份。“我们会删除文件”不算回答，除非说清楚删除什么、何时删除、留下什么。查看文档里有没有留存表，能否提前删除，处理地点和子处理方，是否声明不用于训练，数据处理协议，以及私有化部署选项。文件含个人信息时，《个人信息保护法》第二十一条要求与受托人约定处理目的、期限、处理方式、个人信息种类、保护措施及双方权利义务，并对受托人进行监督（全国人大网）；处理地点在境外时，还须按第三十八条确定向境外提供个人信息的路径。具体的数量门槛与豁免情形，见采购指南的数据处理与合规审查一节，结论由贵单位法务或合规负责人得出。试点时，确认文件在检测后已被删除，且保存的结果按文档写明的期限到期。

Fileverity 的文档写明了什么。 数据保留与安全中的留存表覆盖每一类数据。上传的文件在检测开始时删除，无论如何不会超过文档写明的期限；DELETE /files/{id} 可提前删除。提交的文本评估后即丢弃，从不存储。检测结果保留一段有限的时间，文本结果不含文本本身。文档的页面图像和文字摘录这类证据，保留时间比结果更短，如果需要报告中包含这些证据，请在检测完成后立即下载 PDF 报告。请求日志不记录请求体和响应体。处理地点和子处理方见信任中心，条款见数据处理协议，企业客户可按需申请私有化部署。

审计证据与模型版本

为什么重要。 一个被标记的案件在数月后受到质疑时，您必须能说明检测了什么、何时检测、用的是哪个模型的哪个版本，以及文件此后没有被改动。数据库里一个孤零零的分数做不到这些。如果服务商不通知就更换模型，同一个文件的结果可能发生变化，您就无法把试点结果与生产结果比较，也无法解释两次检测之间的差异。

如何核实。 查看是否为每个结果提供稳定的 ID（便于与案件一同保存）、被检文件的指纹（哈希值）、由时间戳机构签发的可信时间戳（RFC 3161，让时间不只取决于服务商自己的时钟）、可下载的报告，以及第三方无需账号即可确认报告的方式。确认每个结果是否注明确切的模型版本，能否把请求固定到某个版本、该版本保留多久，以及变更与下线如何通知。可信时间戳与 SHA-256 哈希指南说明了哈希与时间戳各自能证明什么。

Fileverity 的文档写明了什么。 图片和文档报告带有报告编号、被检文件的 SHA-256 指纹、RFC 3161 时间戳，以及任何人凭链接无需账号即可使用的公开核验页，另有加盖封印的 PDF。每个结果都注明生成它的快照；fvimg-2 这样的模型 ID 指向一个带日期的快照，把快照 ID 作为 model 传入即可把请求固定在该快照上。v1 的变更是增量式的，并记录在变更日志中，因此客户端应忽略不认识的字段。文本结果带有检测 ID 和生成它的快照。下线某个快照的通知期，应写进您的合同，请以书面方式确认。参见 报告对象、约定 和 更新日志。

计费与测试模式

为什么重要。 价目表会掩盖决定账单的规则：计费单位，失败、取消或重复的检测如何处理，如何取整，以及一个失控的任务最多会花多少钱。您还需要能够在不花钱、不污染生产数据的情况下开发和测试集成。

如何核实。 找到每种类型的计费单位（按图片、按文档、按字符块）和取整规则。确认失败、取消和被拒绝的请求是否计费，是预付费还是订阅制，有没有支出上限、余额不足提醒，以及能与您自己的计数对账的用量报表。好的测试模式从不扣费，适用相同的校验，并明确说明模拟了什么、没模拟什么：耗时、Webhook 和真实结果通常是缺口。试点时，把服务商的用量报表与您自己的日志对账，其中包括一次有意制造的失败。

Fileverity 的文档写明了什么。 API 采用预付费，从工作区余额扣款，没有订阅。价格按每次图片检测、每次文档检测和每个文本字符块计算，每次请求向上取整。图片和文档检测在创建时预留费用，失败或取消时释放；评估开始前就被拒绝的请求不计费。免费额度先于余额使用。每个密钥可设置每月支出上限，余额不足提醒会发送电子邮件和 balance.low Webhook，每次检测在 usage 中报告其费用。测试密钥从不扣费，也不使用免费额度，立即返回固定样例，适用相同的校验、速率限制和错误码，除控制台的测试事件外不发送 Webhook。示例报告编号以 FV-TEST- 开头，没有公开核验页。当前价格见 价格与计费和 API 页面；测试密钥的行为见 身份验证与密钥。

常见问题

应该选同步 API 还是异步 API？

两者本身没有优劣。像纯文本这样的短输入适合同步调用，需要较重分析的文件通常先返回一个状态。关键在于文档定义了完整的生命周期，支持等待、轮询和 Webhook，并且您的代码能处理“进行中”状态。

需要 Webhook，还是轮询就够了？

原型或低流量场景下轮询就够了。Webhook 能节省请求次数和速率限额，更适合生产环境。无论哪种方式，都要验证签名，并处理重复事件和“进行中”状态。

幂等键是标准吗？

它是一种常见约定，一份 IETF 草案对其作了描述，但截至 2026 年 11 月尚未成为 RFC。请把具体行为视为各服务商自己的实现并加以测试。Fileverity 的行为记录在 幂等性页面。

API 好，就说明检测器准确吗？

不能。这些评估项针对的是集成，而不是检测质量。请用您自己的文件和您信得过的标注来评估检测效果，可参考准确率与误报指南和采购指南。

可以免费试用 Fileverity API 吗？

可以。您的第一个工作区含免费额度，测试密钥从不扣费。请按 快速入门操作，条款见 价格与计费。

试点核查清单

分三轮进行试点，并为每个答案留下带日期的记录。第一轮是案头核查：根据每家候选服务商的文档回答全部十项，在写代码前剔除明显不合适的。第二轮用测试密钥：针对测试模式搭建集成。第三轮在真实环境：使用设有较低支出上限的 Live 密钥，以及您有权发送的文件样本。检测质量本身的抽样、标注和评分，请按企业选择 AI 生成图片检测工具的采购指南中的试点方法进行。

请把这些答复与采购指南中的能力覆盖表和评分放在一起。要开始使用 Fileverity，请阅读 API 页面、图片与文档检测页面，以及 快速入门。

作者 Yang Zheng · 审核 Bill Liu