# 身份验证与密钥

> 使用 Bearer API 密钥进行身份验证。内容包括 Live 密钥与测试密钥、测试模式的返回内容、撤销密钥，以及为每个密钥设置每月支出上限。

来源： https://fileverity.com/zh/docs/authentication

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

**带身份验证的请求: cURL**

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

**带身份验证的请求: JavaScript**

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

**带身份验证的请求: Python**

```python
import os
import 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 密钥 | 测试密钥 |
| --- | --- | --- |
| 前缀 | `fv_live_...` | `fv_test_...` |
| 运行模型 | 是 | 否 |
| 从余额或免费额度中扣费 | 是 | 从不 |
| 结果 | 真实结果 | 固定示例 |
| 响应中的 `livemode` | `true` | `false` |
| Webhooks | 会发送 | 不发送 |

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

**示例文本检测（测试密钥）**

```json
{
  "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 密钥。测试密钥从不产生支出。

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

## 身份验证错误

| 错误码 | 状态 | 含义 |
| --- | --- | --- |
| `missing_api_key` | 401 | 未发送 `Authorization: Bearer` 请求头。 |
| `invalid_api_key` | 401 | 密钥格式错误、不存在或已被撤销。 |
| `spend_limit_reached` | 402 | 密钥已达到每月支出上限。 |

完整列表见[错误](https://fileverity.com/zh/docs/errors.md)。