# 快速入门

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

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

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

## 1. 打开控制台

在 [fileverity.com/console](https://fileverity.com/console?lang=zh) 使用邮箱验证码或 Google 账号登录。首次登录会创建一个个人工作区，并带有独立的预付余额。

您的第一个工作区含有 5 次免费图片或文档检测和 5,000 个免费文本字符，无需绑卡。每人一次免费额度，每个企业邮箱域名的次数有限。团队成员请通过邀请加入。免费额度会先于余额使用。参见[价格与计费](https://fileverity.com/zh/docs/pricing.md#free-start)。

## 2. 创建 API 密钥

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

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

**环境变量: Shell**

```bash
export FILEVERITY_API_KEY=fv_test_...
```

## 3. 验证密钥

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

**验证密钥: cURL**

```bash
curl -i 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 },
});
console.log(response.status);
```

**验证密钥: Python**

```python
import os
import requests

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

## 4. 检测一段文本

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

**写入 essay.txt**

```bash
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 the
phone until Monday. I photographed everything before signing, which is the
only reason we have a leg to stand on. In today's fast-paced logistics
landscape, it is essential for businesses to prioritize reliable delivery
performance, as timely and undamaged shipments play a pivotal role in
fostering customer trust and long-term satisfaction. We lost two days. Marta
rebuilt the schedule by hand and the Leeds order still went out late. Moving
forward, it is crucial to implement robust quality assurance measures and
establish clear communication channels, ensuring that all stakeholders remain
aligned and that potential issues are proactively addressed. For now I am
asking for a credit note and a named contact. Not another apology.
EOF
```

**第一次文本检测: cURL**

```bash
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)"
```

**第一次文本检测: JavaScript**

```javascript
import { readFile } from "node:fs/promises";

const response = await fetch("https://api.fileverity.com/v1/text/detections", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.FILEVERITY_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ text: await readFile("essay.txt", "utf8") }),
});
const detection = await response.json();
if (!response.ok) throw new Error(detection.error.code + ": " + detection.error.message);
console.log(detection.verdict, detection.ai_fraction);
```

**第一次文本检测: Python**

```python
import os
import requests

response = requests.post(
    "https://api.fileverity.com/v1/text/detections",
    headers={"Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"]},
    json={"text": open("essay.txt", encoding="utf-8").read()},
)
detection = response.json()
if not response.ok:
    raise RuntimeError(detection["error"]["code"] + ": " + detection["error"]["message"])
print(detection["verdict"], detection["ai_fraction"])
```

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

**响应（Live 密钥）**

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

详细说明（包括偏移量的计算方式）见[文本检测](https://fileverity.com/zh/docs/text-detections.md)。

## 5. 检测一张图片

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

**第一次图片检测: cURL**

```bash
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\"}"
```

**第一次图片检测: JavaScript**

```javascript
import { readFile } from "node:fs/promises";

const headers = { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY };

const form = new FormData();
form.append("file", new Blob([await readFile("photo.jpg")], { type: "image/jpeg" }), "photo.jpg");
const file = await (await fetch("https://api.fileverity.com/v1/files", { method: "POST", headers, body: form })).json();

const response = await fetch("https://api.fileverity.com/v1/analyses", {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json", Prefer: "wait=60" },
  body: JSON.stringify({ model: "fvimg-2", file: file.id }),
});
const analysis = await response.json();
console.log(analysis.status, analysis.summary, analysis.report_url);
```

**第一次图片检测: Python**

```python
import os
import requests

headers = {"Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"]}

file = requests.post("https://api.fileverity.com/v1/files", headers=headers, files={"file": open("photo.jpg", "rb")}).json()

response = requests.post(
    "https://api.fileverity.com/v1/analyses",
    headers={**headers, "Prefer": "wait=60"},
    json={"model": "fvimg-2", "file": file["id"]},
)
analysis = response.json()
print(analysis["status"], analysis["summary"], analysis["report_url"])
```

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

**响应（Live 密钥）**

```json
{
  "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 端点](https://fileverity.com/zh/docs/webhooks.md)以代替轮询。
- 在 POST 请求中发送 `Idempotency-Key`，这样重试就不会让同一次检测运行两次。参见[幂等性](https://fileverity.com/zh/docs/idempotency.md)。

各项检测检查什么、团队在哪些场景中使用，请参阅 [AI 生成图片检测 API](https://fileverity.com/zh/api/ai-image-detection) 和[文档伪造检测 API](https://fileverity.com/zh/api/document-fraud-detection)。

下一步：[示例代码](https://fileverity.com/zh/docs/sample-code.md)提供了每种检测和 Webhook 的完整 Node.js 与 Python 程序。接着请阅读[身份验证与密钥](https://fileverity.com/zh/docs/authentication.md)、[错误](https://fileverity.com/zh/docs/errors.md)和 [API 参考](https://fileverity.com/zh/docs/api-reference.md)。如果遇到问题，请发邮件至 [hello@fileverity.com](mailto:hello@fileverity.com) 或使用[联系页面](https://fileverity.com/zh/contact)，并附上 `x-request-id` 响应头中的请求 ID。