# 图片鉴别

> 通过 POST /images/detections 判断整张图片是否由 AI 生成。一次同步调用：请求与响应字段、结论取值、限制和计费。

来源： https://fileverity.com/zh/docs/image-detections

`POST /images/detections` 运行 AI生成图片鉴别。它用 `vereye-2-detect` 判断整张图片是否由 AI 生成，所依据的模型、内容凭证、AI 标识和水印与图片核验报告（`vereye-2`）相同，因此两者在 AI 生成这一问题上给出相同的结论。该调用是同步的：结果就在响应中。

它不检查局部编辑，包括对照片局部的 AI 编辑，也不返回报告编号或 PDF。如需编辑痕迹、来源和任何人都能核验的记录，请用 `vereye-2` 创建[分析](https://fileverity.com/zh/docs/analyses.md)。

**请求: cURL**

```bash
curl https://api.fileverity.com/v1/images/detections \
  -H "Authorization: Bearer $FILEVERITY_API_KEY" \
  -H "Idempotency-Key: 6b9d1c1e-3b0f-4c0a-9a53-2d1c9d6b7e11" \
  -F file=@photo.jpg
```

**请求: JavaScript**

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

const form = new FormData();
form.append("file", new Blob([await readFile("photo.jpg")], { type: "image/jpeg" }), "photo.jpg");

const response = await fetch("https://api.fileverity.com/v1/images/detections", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY, "Idempotency-Key": randomUUID() },
  body: form,
});
const detection = await response.json();
console.log(detection.verdict, detection.ai);
```

**请求: Python**

```python
import os
import uuid
import requests

response = requests.post(
    "https://api.fileverity.com/v1/images/detections",
    headers={"Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"], "Idempotency-Key": str(uuid.uuid4())},
    files={"file": open("photo.jpg", "rb")},
)
detection = response.json()
print(detection["verdict"], detection["ai"])
```

## 请求体

以 `multipart/form-data` 把图片放在 `file` 字段中发送，最大 4 MB。更大的图片（最大 10 MB）请先用 [`POST /files`](https://fileverity.com/zh/docs/files.md) 上传，再改为发送 JSON：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `file` | file 或 string | 是 | multipart 请求中的图片，或 JSON 请求中已上传图片的 ID。支持 JPEG、PNG、WEBP，最大 4000 万像素。文件 ID 在检测后即被消耗。 |
| `model` | string | 否 | 默认为 `vereye-2-detect`。接受模型 ID 或其快照 ID `vereye-2-detect-2026-10-30`。 |

未知字段会被拒绝，并返回 `invalid_parameter`。

## 响应

**200 OK**

```json
{
  "id": "idet_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "image.detection",
  "created": 1794096000,
  "model": "vereye-2-detect-2026-10-30",
  "livemode": true,
  "verdict": "ai_generated",
  "ai": {
    "key": "very_likely",
    "basis": "detected",
    "strength": "strong",
    "likelihood": 100
  },
  "generator": null,
  "signals": [
    {
      "id": "model_1",
      "state": "ai"
    },
    {
      "id": "model_2",
      "state": "ai"
    },
    {
      "id": "credentials",
      "state": "none"
    },
    {
      "id": "watermark",
      "state": "none"
    },
    {
      "id": "label",
      "state": "none"
    },
    {
      "id": "tool_data",
      "state": "none"
    },
    {
      "id": "camera",
      "state": "none"
    }
  ],
  "regions": [
    {
      "x": 0,
      "y": 0,
      "w": 576,
      "h": 512,
      "level": 3
    },
    {
      "x": 576,
      "y": 0,
      "w": 384,
      "h": 512,
      "level": 3
    },
    {
      "x": 960,
      "y": 0,
      "w": 576,
      "h": 512,
      "level": 2
    },
    {
      "x": 0,
      "y": 512,
      "w": 576,
      "h": 512,
      "level": 3
    },
    {
      "x": 576,
      "y": 512,
      "w": 384,
      "h": 512,
      "level": 3
    },
    {
      "x": 960,
      "y": 512,
      "w": 576,
      "h": 512,
      "level": 3
    }
  ],
  "candidates": [
    {
      "name": "Midjourney",
      "score": 0.65
    },
    {
      "name": "OpenAI",
      "score": 0.25
    }
  ],
  "quality": {
    "overall": "fair",
    "resolution": "good",
    "compression": "fair",
    "metadata": "fair",
    "distribution": "good"
  },
  "limits": [
    "no_metadata"
  ],
  "image": {
    "width": 1536,
    "height": 1024,
    "format": "jpeg",
    "jpeg_quality": 85
  },
  "usage": {
    "credits": 4
  }
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 鉴别 ID，前缀为 `idet_`。 |
| `object` | string | 始终为 `image.detection`。 |
| `created` | integer | Unix 时间戳。 |
| `model` | string | 生成该结果的快照。 |
| `livemode` | boolean | 测试密钥为 `false`。 |
| `verdict` | string | `ai_generated`：图片由 AI 生成。`no_ai_signs`：没有任何迹象指向 AI 生成。`inconclusive`：证据不足以判定。 |
| `ai` | object | 关于 AI 生成的结论，取值与[图片报告](https://fileverity.com/zh/docs/analyses.md#report-image)中的 `questions.ai` 相同。 |
| `generator` | object 或 null | 文件通过内容凭证、元数据或水印声明的生成器，包含 `name` 和 `basis`。文件未声明时为 `null`。 |
| `signals` | array | 答案所依据的各项检查，每项包含 `id` 和 `state`。参见[信号](#signals)。 |
| `regions` | 数组或 null | 覆盖图片的粗网格。每个单元格包含以所显示图片的像素为单位的 `x`、`y`、`w` 和 `h`，以及表示生成特征强度的 `level`（0 到 3）。图片太小、无法划分网格时为 `null`。 |
| `candidates` | array | 像素特征与该图片最接近的生成模型，最多三个，每个包含 `name` 和 0 到 1 的 `score`。仅当结论为 `ai_generated` 时有内容。 |
| `quality` | object 或 null | 文件对分析的支持程度：`overall`、`resolution`、`compression`、`metadata` 和 `distribution`，取值均为 `good`、`fair` 或 `poor`。 |
| `limits` | array | 影响结果的因素：`low_resolution`、`heavy_compression`、`platform_copy`、`no_metadata` 或 `models_disagree`。 |
| `image` | object | 显示时的 `width` 和 `height`、`format`，以及 `jpeg_quality`（估计的 JPEG 质量，或 `null`）。 |
| `usage` | object | 扣除的 `credits`。 |

## 如何解读结论

| `ai.key` | `verdict` | 含义 |
| --- | --- | --- |
| `labelled` | `ai_generated` | 内容凭证、AI 标识或水印声明了 AI 生成。可信凭证的 `ai.basis` 为 `verified`，否则为 `declared` 或 `detected`。 |
| `very_likely`, `suspected` | `ai_generated` | 像素显示出 AI 生成的迹象，证据较强，或各信号之间略有分歧。 |
| `undecided` | `inconclusive` | 信号较弱，或相互矛盾。 |
| `low`, `very_low` | `no_ai_signs` | 像素和元数据中均未发现指向 AI 生成的迹象。 |

`ai.strength` 为 `strong`、`moderate` 或 `limited`，表示证据对该结论的支持强度。`ai.likelihood` 以 5 为步长，取值 0 到 100；结论为 `labelled` 时为 `null`。

> **注意。** `no_ai_signs` 并不说明照片真实或未经编辑。AI生成图片鉴别不检查编辑痕迹。如果决定取决于此，请运行图片核验报告，并由人工复核结果。

## 信号

`signals` 列出已执行的每一项检查，便于了解答案的依据。`state` 为 `ai` 表示该项指向 AI 生成。

| `id` | `state` | 检查项 |
| --- | --- | --- |
| `model_1`, `model_2` | `ai`, `unclear`, `clear`, `unavailable` | 两套独立训练的模型，对像素进行分析。 |
| `credentials` | `ai`, `ai_unverified`, `other`, `none` | 内容凭证（C2PA）。`ai_unverified`：凭证声明为 AI 生成，但签发方未能核验。`other`：凭证存在，且未声明 AI 生成。 |
| `watermark` | `ai`, `none`, `unavailable` | 开源生成工具嵌入像素的不可见水印。 |
| `label` | `ai`, `none` | 元数据中的 AI 生成声明，例如 IPTC 数字来源类型。 |
| `tool_data` | `ai`, `none` | 保存在文件中的提示词、参数或生成工具名称。 |
| `camera` | `present`, `none` | 相机品牌、型号和曝光参数。这些信息可以被修改，本接口不对其进行核验。 |

`regions` 展示生成特征最强的位置。3 级的单元格带有明显的生成特征。当结论为 `no_ai_signs` 而部分单元格为 3 级时，图片的局部可能由 AI 生成或经 AI 编辑：本接口不检查局部编辑，请使用图片核验报告。

> **注意。** `candidates` 仅供参考，不代表确认。它按像素特征的相似程度对生成模型排序，参考范围之外的生成工具会显示为与它最相近的一类。文件自身写明生成工具时，请以 `generator` 为准。

## 计费

- AI生成图片鉴别每张图片 4 积分。
- 同一工作区内，同一张图片在 7 天内做过 AI生成图片鉴别的，其图片核验报告为 36 积分，而不是 40 积分：鉴别所用的积分只计一次。分析会在 `usage.credits` 中报告实际扣费。
- 评估前即被拒绝的请求不收费：参数无效、文件不受支持或已损坏、超出大小限制等。在服务内部失败的检测（`service_unavailable`、`analysis_failed`）会被释放，不收费。
- 积分不足时返回 `insufficient_balance`（402）。

## 存储的内容

图片在检测后即被删除。Fileverity 会保留不含图片的结果（结论、答案、生成器、信号、区域、候选、质量、尺寸、文件的 SHA-256 指纹和用量）7 天，以便控制台展示，并便于计费与审计。使用相同 `Idempotency-Key` 重试的请求，24 小时内会得到已保存的结果。图片鉴别是同步的：它们不会出现在 `GET /analyses` 中，也不会发送 Webhook 事件。测试密钥不记录任何内容。参见[数据保留与安全](https://fileverity.com/zh/docs/security.md)。

## 错误

| 错误码 | 状态 | 原因 |
| --- | --- | --- |
| `missing_parameter` | 400 | 缺少 `file` 字段。 |
| `invalid_parameter` | 400 | 字段类型错误、发送了未知字段、模型不是图片鉴别模型，或 `Idempotency-Key` 无效。 |
| `file_not_found` | 400 | 文件 ID 未知、已过期或已被使用。 |
| `unsupported_file`, `invalid_file` | 415, 422 | 文件不是 JPEG、PNG 或 WebP 图片，或已损坏。 |
| `file_too_large`, `too_many_pixels` | 413 | multipart 文件超过 4 MB，上传的文件超过 10 MB，或图片超过 4000 万像素。 |
| `unsupported_media_type`, `invalid_json` | 415, 400 | 请求体既不是 `multipart/form-data`，也不是 JSON 对象。 |
| `model_not_found` | 404 | `model` 未知。 |
| `insufficient_balance`, `spend_limit_reached` | 402 | 余额或密钥的每月上限不足以支付该请求。 |
| `idempotency_mismatch`, `idempotency_in_progress` | 409 | 该 `Idempotency-Key` 曾用于不同的请求体，或其首次请求仍在运行。 |
| `service_unavailable`, `analysis_failed` | 503, 502 | 检测服务暂时不可用或繁忙。未扣费，请重试。`service_unavailable` 会带有 `retry-after` 响应头。 |

> **注意。** 请发送 `Idempotency-Key`，这样超时后重试就不会重复计费。参见[幂等性](https://fileverity.com/zh/docs/idempotency.md)。

