身份验证与密钥

每个请求都需要 API 密钥，并以 Bearer 令牌的形式放在 Authorization 请求头中发送。

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

const response = await fetch("https://api.fileverity.com/v1/models", {  headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY },});

import osimport requests requests.get("https://api.fileverity.com/v1/models", headers={"Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"]})

密钥属于机密信息。请从您的服务器调用 API，将密钥保存在环境变量或密钥管理服务中，切勿放入浏览器端代码或移动应用。

Live 密钥与测试密钥#

密钥由前缀 fv_live_ 或 fv_test_ 加 40 位字母和数字组成。前缀决定模式。

两种模式共用同一个工作区，使用相同的接口、校验规则、速率限制和错误码，因此可以先用测试密钥开发，再换用 Live 密钥上线。

测试模式的行为#

• 文本检测：请求按与 Live 请求相同的方式校验，最小长度、最大长度和语言检查依然适用。响应是固定的 human 结果，其中 score 和 ai_fraction 均为 0，不含 segments。usage 根据您的文本计算。不会扣费，也不会留下记录。
• 文件：上传的文件会经过校验，但文件内容不会被存储；JSON 上传请求返回的是测试上传对象，而不是真实的预签名 URL（upload.test 为 true），且文件状态已是 uploaded。文件按模式隔离：测试密钥无法读取 Live 文件，Live 密钥也无法读取测试文件。
• 创建分析：立即返回 200 和 status: succeeded，结果是固定的示例，风险等级为 L2，处置建议为 accept，并带有 livemode: false。分析 ID 以 an_test 开头，相同的文件对应相同的 ID。报告编号以 FV-TEST- 开头，没有公开核验页。示例报告只包含示例中列出的字段。
• 获取分析：仅适用于示例分析 ID。列出分析始终返回空列表，取消返回 not_cancelable，也没有示例 PDF。测试密钥无法读取 Live 分析或 Live 报告 PDF。

{  "id": "tdet_Qm4vB7nP1sK8tL3wR6yZ2cXa",  "object": "text.detection",  "created": 1793664000,  "model": "fvdoc-3-text-2026-11-03",  "livemode": false,  "language": "en",  "verdict": "human",  "score": 0,  "ai_fraction": 0,  "segments": [],  "usage": {    "characters": 1412,    "free_characters": 0,    "billed_units": 2  }}

创建与撤销密钥#

在控制台的 API 密钥页面管理密钥。

• 创建：为密钥命名并选择模式。完整密钥只显示一次。Fileverity 只保存 SHA-256 哈希值和最后四个字符，因此丢失的密钥无法找回，请创建新密钥。
• 数量限制：每个工作区最多可有 20 个有效密钥。超出后，创建密钥会失败并返回 key_limit。
• 最后使用：控制台会显示每个密钥最近一次发出请求的时间。
• 撤销：使用已撤销密钥的请求会立即失败，并返回 invalid_api_key。
• 成员离开：成员离开工作区或被移除时，其创建的密钥会被撤销。请使用会长期留在工作区的账号创建生产环境密钥。

如果密钥泄露#

1. 创建一个新密钥。
2. 更新您的软件，改用新密钥。
3. 撤销旧密钥。

每月支出上限#

每个密钥都可以设置各自的每月支出上限，金额为整数美元。只有工作区所有者和管理员可以设置或更改上限，可在创建密钥时设置，也可以之后通过修改上限设置。未设上限的密钥仅受您的余额限制。

• 上限统计该密钥在当前 UTC 自然月内的支出，并在每月 1 日重置。
• 会使密钥超出上限的请求，会在开始处理之前被拒绝并返回 spend_limit_reached（HTTP 402），且不收费。
• 免费额度内的检测不收费，也不计入上限。失败和已取消的检测不收费，也不计入上限。
• 上限适用于 Live 密钥。测试密钥从不产生支出。

为每个服务或环境使用单独的密钥，并设置各自的上限。这样，即使某个任务失控，其支出也不会超过该密钥的上限。

身份验证错误#

完整列表见错误。