跳至正文

Fileverity API 文档

快速入门

创建工作区、创建 API 密钥,并使用 cURL、JavaScript fetch 或 Python requests 运行您的第一次文本和图片检测。

查看 Markdown更新于 2026-11-04

本页带您从注册走到第一批检测结果。您需要一个 Fileverity 账号和一个装有 curl 与 jq 的终端;运行图片示例还需要一个 JPEG、PNG 或 WebP 文件。

1. 打开控制台

在 fileverity.com/console 使用邮箱验证码或 Google 账号登录。首次登录会创建一个个人工作区,并带有独立的预付余额。

您的第一个工作区含有 5 次免费图片或文档检测和 5,000 个免费文本字符,无需绑卡。每人一次免费额度,每个企业邮箱域名的次数有限。团队成员请通过邀请加入。免费额度会先于余额使用。参见价格与计费。

2. 创建 API 密钥

打开 API 密钥,选择创建密钥,为其命名并选择模式。请先创建 Test 密钥:它返回固定的示例结果,不会调用模型,也不会扣费。完整密钥只显示一次,请立即复制。

不要把密钥提交到版本控制系统,也不要放进浏览器端代码。请将它导出为环境变量:

export FILEVERITY_API_KEY=fv_test_...

3. 验证密钥

GET /models 可使用任何有效密钥调用,且不会扣费。返回 200 并列出模型,说明密钥有效。返回 401 则说明密钥缺失、输入有误或已被撤销。

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

4. 检测一段文本

向 POST /text/detections 发送至少 100 个词的纯文本。示例从文件中读取文本,因此请先把任意一段不少于 100 个词的文字保存为 essay.txt。下面的命令会写入一段示例文本:

cat > essay.txt <<'EOF'Honestly, the delivery was a mess. The driver turned up at six in the evening,the pallet was wet on one side, and nobody at the depot would pick up thephone until Monday. I photographed everything before signing, which is theonly reason we have a leg to stand on. In today's fast-paced logisticslandscape, it is essential for businesses to prioritize reliable deliveryperformance, as timely and undamaged shipments play a pivotal role infostering customer trust and long-term satisfaction. We lost two days. Martarebuilt the schedule by hand and the Leeds order still went out late. Movingforward, it is crucial to implement robust quality assurance measures andestablish clear communication channels, ensuring that all stakeholders remainaligned and that potential issues are proactively addressed. For now I amasking for a credit note and a named contact. Not another apology.EOF
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)"

使用测试密钥时,响应固定为人类撰写文本的结果。使用 Live 密钥时,响应如下:

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

详细说明(包括偏移量的计算方式)见文本检测。

5. 检测一张图片

图片和文档需要两次调用:先上传文件,再创建引用该文件的分析。每个分析对应一次图片或文档检测。Prefer: wait=60 会让请求保持等待,直到结果就绪,最长 60 秒。

FILE_ID=$(curl -s https://api.fileverity.com/v1/files \  -H "Authorization: Bearer $FILEVERITY_API_KEY" \  -F file=@photo.jpg | jq -r .id) 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_ID\"}"

分析完成时返回 200,其中 status: succeeded,并包含简短的 summary 和完整的 result.report。如果等待超时而结果仍未就绪,则返回 202 和 status: processing;之后可用 GET /analyses/{id} 获取,或通过 Webhook 接收通知。参见分析。

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

使用测试密钥时,文件只会被校验而不会被存储,分析会立即返回固定的示例结果。其报告编号以 FV-TEST- 开头,没有公开核验页。

6. 正式上线

  • 在控制台中创建 Live 密钥,并用它替换测试密钥。同样的代码无需修改即可运行。
  • 可以使用免费额度,也可以在余额页面为工作区余额充值。最低充值金额为 US$19。
  • 为密钥设置每月支出上限,并添加 Webhook 端点以代替轮询。
  • 在 POST 请求中发送 Idempotency-Key,这样重试就不会让同一次检测运行两次。参见幂等性。

各项检测检查什么、团队在哪些场景中使用,请参阅 AI 生成图片检测 API 和文档伪造检测 API。

下一步:示例代码提供了每种检测和 Webhook 的完整 Node.js 与 Python 程序。接着请阅读身份验证与密钥、错误和 API 参考。如果遇到问题,请发邮件至 hello@fileverity.com 或使用联系页面,并附上 x-request-id 响应头中的请求 ID。