Fileverity API 文档
图片鉴别
通过 POST /images/detections 判断整张图片是否由 AI 生成。一次同步调用:请求与响应字段、结论取值、限制和计费。
POST /images/detections 运行 AI生成图片鉴别。它用 vereye-2-detect 判断整张图片是否由 AI 生成,所依据的模型、内容凭证、AI 标识和水印与图片核验报告(vereye-2)相同,因此两者在 AI 生成这一问题上给出相同的结论。该调用是同步的:结果就在响应中。
它不检查局部编辑,包括对照片局部的 AI 编辑,也不返回报告编号或 PDF。如需编辑痕迹、来源和任何人都能核验的记录,请用 vereye-2 创建分析。
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.jpgimport { 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);import osimport uuidimport 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 上传,再改为发送 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。
响应
{ "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 生成的结论,取值与图片报告中的 questions.ai 相同。 |
generator | object 或 null | 文件通过内容凭证、元数据或水印声明的生成器,包含 name 和 basis。文件未声明时为 null。 |
signals | array | 答案所依据的各项检查,每项包含 id 和 state。参见信号。 |
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 事件。测试密钥不记录任何内容。参见数据保留与安全。
错误
| 错误码 | 状态 | 原因 |
|---|---|---|
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,这样超时后重试就不会重复计费。参见幂等性。